monoco-toolkit 0.3.10__py3-none-any.whl → 0.3.12__py3-none-any.whl

monoco/features/issue/core.py

@@ -46,6 +46,30 @@ def get_issue_dir(issue_type: str, issues_root: Path) -> Path:
     return issues_root / folder
 
 
+def _parse_isolation_ref(ref: str) -> str:
+    """
+    Parse isolation ref and strip any 'branch:' or 'worktree:' prefix.
+    
+    The isolation.ref field may contain prefixes like 'branch:feat/xxx' or 'worktree:xxx'
+    for display/logging purposes, but git commands need the raw branch name.
+    
+    Args:
+        ref: The isolation ref string, may contain prefix
+        
+    Returns:
+        The clean branch name without prefix
+    """
+    if not ref:
+        return ref
+    
+    # Strip known prefixes
+    for prefix in ("branch:", "worktree:"):
+        if ref.startswith(prefix):
+            return ref[len(prefix):]
+    
+    return ref
+
+
 def _get_slug(title: str) -> str:
     slug = title.lower()
     # Replace non-word characters (including punctuation, spaces) with hyphens
@@ -108,6 +132,8 @@ def _serialize_metadata(metadata: IssueMetadata) -> str:
         data["domains"] = []
     if "files" not in data:
         data["files"] = []
+    if "solution" not in data:
+        data["solution"] = None
 
     # Custom YAML Dumper to preserve None as 'null' and order
     # Helper to order keys: id, uid, type, status, stage, title, ... graph ...
@@ -147,6 +173,10 @@ def _serialize_metadata(metadata: IssueMetadata) -> str:
     if "criticality" in data:
         ordered_data["criticality"] = data["criticality"]
 
+    # Add solution if present (for template generation)
+    if "solution" in data:
+        ordered_data["solution"] = data["solution"]
+
     # Add remaining
     for k, v in data.items():
         if k not in ordered_data:
@@ -161,6 +191,10 @@ def _serialize_metadata(metadata: IssueMetadata) -> str:
         yaml_header = yaml_header.replace(
             "parent: null", "parent: null # <EPIC-ID> Optional"
         )
+    if "solution" in ordered_data and ordered_data["solution"] is None:
+        yaml_header = yaml_header.replace(
+            "solution: null", "solution: null # implemented, cancelled, wontfix, duplicate"
+        )
 
     return yaml_header
 
@@ -189,15 +223,19 @@ def parse_issue_detail(file_path: Path) -> Optional[IssueDetail]:
         return None
 
 
-def find_next_id(issue_type: str, issues_root: Path) -> str:
+def find_next_id(issue_type: str, issues_root: Path, include_archived: bool = False) -> str:
     prefix_map = get_prefix_map(issues_root)
     prefix = prefix_map.get(issue_type, "ISSUE")
     pattern = re.compile(rf"{prefix}-(\d+)")
     max_id = 0
 
     base_dir = get_issue_dir(issue_type, issues_root)
-    # Scan all subdirs: open, backlog, closed
-    for status_dir in ["open", "backlog", "closed"]:
+    # Scan all subdirs: open, backlog, closed, archived (optional)
+    status_dirs = ["open", "backlog", "closed"]
+    if include_archived:
+        status_dirs.append("archived")
+    
+    for status_dir in status_dirs:
         d = base_dir / status_dir
         if d.exists():
             for f in d.rglob("*.md"):
@@ -388,7 +426,15 @@ def get_available_actions(meta: IssueMetadata) -> List[Any]:
     return actions
 
 
-def find_issue_path(issues_root: Path, issue_id: str) -> Optional[Path]:
+def find_issue_path(issues_root: Path, issue_id: str, include_archived: bool = True) -> Optional[Path]:
+    """
+    Find the path of an issue file.
+    
+    Args:
+        issues_root: Root directory of issues
+        issue_id: Issue ID to find
+        include_archived: Whether to search in archived directory (default: True for find operations)
+    """
     parsed = IssueID(issue_id)
 
     if not parsed.is_local:
@@ -414,7 +460,7 @@ def find_issue_path(issues_root: Path, issue_id: str) -> Optional[Path]:
             return None
 
         # Recursively search in member project
-        return find_issue_path(member_issues, parsed.local_id)
+        return find_issue_path(member_issues, parsed.local_id, include_archived)
 
     # Local Search
     try:
@@ -428,12 +474,243 @@ def find_issue_path(issues_root: Path, issue_id: str) -> Optional[Path]:
         return None
 
     base_dir = get_issue_dir(issue_type, issues_root)
-    # Search in all status subdirs recursively
-    for f in base_dir.rglob(f"{parsed.local_id}-*.md"):
-        return f
+    # Search in standard status subdirs first
+    for status_dir in ["open", "backlog", "closed"]:
+        d = base_dir / status_dir
+        if d.exists():
+            for f in d.rglob(f"{parsed.local_id}-*.md"):
+                return f
+    
+    # Search in archived if enabled
+    if include_archived:
+        archived_dir = base_dir / "archived"
+        if archived_dir.exists():
+            for f in archived_dir.rglob(f"{parsed.local_id}-*.md"):
+                return f
     return None
 
 
+def find_issue_path_across_branches(
+    issues_root: Path, 
+    issue_id: str, 
+    project_root: Optional[Path] = None,
+    include_archived: bool = True
+) -> Tuple[Optional[Path], Optional[str]]:
+    """
+    Find issue path across all local git branches.
+    
+    Implements the "Golden Path" logic:
+    - If issue found in exactly one branch -> return it silently
+    - If issue found in multiple branches -> raise error (conflict)
+    - If issue not found in any branch -> return None
+    
+    Args:
+        issues_root: Root directory of issues
+        issue_id: Issue ID to find
+        project_root: Project root (defaults to issues_root.parent)
+        include_archived: Whether to search in archived directory
+        
+    Returns:
+        Tuple of (file_path, branch_name) or (None, None) if not found
+        
+    Raises:
+        RuntimeError: If issue found in multiple branches (conflict)
+    """
+    # First, try to find in current working tree
+    local_path = find_issue_path(issues_root, issue_id, include_archived)
+    
+    # Determine project root
+    if project_root is None:
+        project_root = issues_root.parent
+    
+    # If not a git repo, just return local result
+    if not git.is_git_repo(project_root):
+        return (local_path, None) if local_path else (None, None)
+    
+    # Get current branch
+    current_branch = git.get_current_branch(project_root)
+    
+    # Search in all branches to detect conflicts (FIX-0006)
+    # If found locally, we still check other branches to detect potential duplicate files (conflict)
+    if local_path:
+        # Get relative path for git checking
+        try:
+            rel_path = local_path.relative_to(project_root)
+        except ValueError:
+            # If path is outside project root, we can't search other branches anyway
+            return local_path, current_branch
+            
+        conflicting_branches = _find_branches_with_file(project_root, str(rel_path), current_branch)
+        
+        # SPECIAL CASE (FIX-0006): During 'issue close' or similar operations,
+        # it is expected that the file exists in the feature branch (isolation branch)
+        # and now in the target branch (e.g. main). This is NOT a conflict.
+        if conflicting_branches:
+            # Try to parse metadata to see if these "conflicts" are actually the isolation branch
+            try:
+                meta = parse_issue(local_path)
+                if meta and meta.isolation:
+                    iso_type = getattr(meta.isolation, "type", None)
+                    iso_ref = getattr(meta.isolation, "ref", None)
+                    
+                    source_branch = None
+                    if iso_type == "branch":
+                        source_branch = iso_ref
+                    elif iso_ref and iso_ref.startswith("branch:"):
+                        source_branch = iso_ref[7:]
+                    
+                    if source_branch:
+                        # Filter out the source branch from conflicts
+                        conflicting_branches = [b for b in conflicting_branches if b != source_branch]
+            except Exception:
+                # If parsing fails, stick with raw conflicts to be safe
+                pass
+
+        if conflicting_branches:
+             raise RuntimeError(
+                f"Issue {issue_id} found in multiple branches: {current_branch}, {', '.join(conflicting_branches)}. "
+                f"Please resolve the conflict by merging branches or deleting duplicate issue files."
+            )
+        return local_path, current_branch
+        
+    # Not found locally, search in all branches
+    return _search_issue_in_branches(issues_root, issue_id, project_root, include_archived)
+
+
+def _find_branches_with_file(project_root: Path, rel_path: str, exclude_branch: str) -> List[str]:
+    """
+    Find all branches (except excluded) that contain the given file path.
+    
+    Args:
+        project_root: Project root path
+        rel_path: Relative path from project root
+        exclude_branch: Branch to exclude from search
+        
+    Returns:
+        List of branch names containing the file
+    """
+    branches_with_file = []
+    
+    # Get all local branches
+    code, stdout, _ = git._run_git(["branch", "--format=%(refname:short)"], project_root)
+    if code != 0:
+        return []
+    
+    all_branches = [b.strip() for b in stdout.splitlines() if b.strip()]
+    
+    for branch in all_branches:
+        if branch == exclude_branch:
+            continue
+            
+        # Check if file exists in this branch
+        code, _, _ = git._run_git(["show", f"{branch}:{rel_path}"], project_root)
+        if code == 0:
+            branches_with_file.append(branch)
+    
+    return branches_with_file
+
+
+def _search_issue_in_branches(
+    issues_root: Path,
+    issue_id: str,
+    project_root: Path,
+    include_archived: bool = True
+) -> Tuple[Optional[Path], Optional[str]]:
+    """
+    Search for an issue file across all branches.
+    
+    Returns:
+        Tuple of (file_path, branch_name) or (None, None)
+        
+    Raises:
+        RuntimeError: If issue found in multiple branches
+    """
+    parsed = IssueID(issue_id)
+    
+    if not parsed.is_local:
+        # For workspace issues, just use standard find
+        path = find_issue_path(issues_root, issue_id, include_archived)
+        return (path, None) if path else (None, None)
+    
+    # Get issue type from prefix
+    try:
+        prefix = parsed.local_id.split("-")[0].upper()
+    except IndexError:
+        return None, None
+    
+    reverse_prefix_map = get_reverse_prefix_map(issues_root)
+    issue_type = reverse_prefix_map.get(prefix)
+    if not issue_type:
+        return None, None
+    
+    # Build possible paths to search
+    base_dir = get_issue_dir(issue_type, issues_root)
+    rel_base = base_dir.relative_to(project_root)
+    
+    status_dirs = ["open", "backlog", "closed"]
+    if include_archived:
+        status_dirs.append("archived")
+    
+    # Search pattern: Issues/{Type}/{status}/{issue_id}-*.md
+    found_in_branches: List[Tuple[str, str]] = []  # (branch, file_path)
+    
+    # Get all local branches
+    code, stdout, _ = git._run_git(["branch", "--format=%(refname:short)"], project_root)
+    if code != 0:
+        return None, None
+    
+    all_branches = [b.strip() for b in stdout.splitlines() if b.strip()]
+    
+    for branch in all_branches:
+        # List files in each status directory for this branch
+        for status_dir in status_dirs:
+            dir_path = f"{rel_base}/{status_dir}"
+            
+            # List all files in this directory on the branch
+            code, stdout, _ = git._run_git(
+                ["ls-tree", "-r", "--name-only", branch, dir_path], 
+                project_root
+            )
+            
+            if code != 0 or not stdout.strip():
+                continue
+            
+            # Find matching issue file (Handling quoted paths from git ls-tree)
+            pattern = f"{parsed.local_id}-"
+            for line in stdout.splitlines():
+                line = line.strip()
+                # Git quotes non-ASCII paths: "Issues/Chores/...md"
+                if line.startswith('"') and line.endswith('"'):
+                    line = line[1:-1]
+                
+                if pattern in line and line.endswith(".md"):
+                    found_in_branches.append((branch, line))
+    
+    if not found_in_branches:
+        return None, None
+    
+    if len(found_in_branches) > 1:
+        # Found in multiple branches - conflict
+        branches = [b for b, _ in found_in_branches]
+        raise RuntimeError(
+            f"Issue {issue_id} found in multiple branches: {', '.join(branches)}. "
+            f"Please resolve the conflict by merging branches or deleting duplicate issue files."
+        )
+    
+    # Golden path: exactly one match
+    branch, file_path = found_in_branches[0]
+    
+    # Checkout the file to working tree
+    try:
+        git.git_checkout_files(project_root, branch, [file_path])
+        full_path = project_root / file_path
+        return full_path, branch
+    except Exception:
+        # If checkout fails, return the path anyway - caller can handle
+        full_path = project_root / file_path
+        return full_path, branch
+
+
 def update_issue(
     issues_root: Path,
     issue_id: str,
@@ -867,7 +1144,7 @@ def prune_issue_resources(
         return []
 
     if issue.isolation.type == IsolationType.BRANCH:
-        branch = issue.isolation.ref
+        branch = _parse_isolation_ref(issue.isolation.ref)
         current = git.get_current_branch(project_root)
         if current == branch:
             raise RuntimeError(
@@ -893,7 +1170,7 @@ def prune_issue_resources(
             # Also delete the branch associated?
             # Worktree create makes a branch. When removing worktree, branch remains.
             # Usually we want to remove the branch too if it was created for this issue.
-            branch = issue.isolation.ref
+            branch = _parse_isolation_ref(issue.isolation.ref)
             if branch and git.branch_exists(project_root, branch):
                 # We can't delete branch if it is checked out in the worktree we just removed?
                 # git worktree remove unlocks the branch.
@@ -951,7 +1228,9 @@ def sync_issue_files(issues_root: Path, issue_id: str, project_root: Path) -> Li
     target_ref = None
 
     if issue.isolation and issue.isolation.ref:
-        target_ref = issue.isolation.ref
+        target_ref = _parse_isolation_ref(issue.isolation.ref)
+        if target_ref == "current":
+             target_ref = git.get_current_branch(project_root)
     else:
         # Heuristic Search
         # 1. Is current branch related?
@@ -1003,6 +1282,118 @@ def sync_issue_files(issues_root: Path, issue_id: str, project_root: Path) -> Li
     return []
 
 
+def merge_issue_changes(
+    issues_root: Path, issue_id: str, project_root: Path
+) -> List[str]:
+    """
+    Perform Smart Atomic Merge or selection checkout of touched files.
+    Ensures safe mainline synchronization by only merging files tracked in 'files' field.
+    """
+    path = find_issue_path(issues_root, issue_id)
+    if not path:
+        raise FileNotFoundError(f"Issue {issue_id} not found.")
+
+    issue = parse_issue(path)
+    if not issue:
+        raise ValueError(f"Could not parse issue {issue_id}")
+
+    if not issue.files:
+        # If no files tracked, nothing to merge.
+        return []
+
+    # Determine Source (Feature Branch)
+    # We prioritize what's in the issue metadata on LOCAL (main).
+    # If not there, we try heuristic.
+    source_ref = None
+    if issue.isolation and issue.isolation.ref:
+        source_ref = _parse_isolation_ref(issue.isolation.ref)
+    else:
+        # Heuristic: Search for branch by convention
+        # We can't use 'current' here safely if we are on main,
+        # but let's assume we might be calling this from elsewhere?
+        # Actually, for 'close', we are likely on main.
+        # So we search for a branch named 'feat/{id}-*' or similar?
+        pass
+
+    # If local metadata doesn't have isolation ref, we might be stuck.
+    # But let's assume valid workflow.
+    if not source_ref:
+          # Try to find a branch starting with feat/{id} or {id}
+          # This is a bit weak, needs better implementation in 'git' or 'issue' module
+          # For now, if we can't find it, we error.
+          pass
+
+    if not source_ref or not git.branch_exists(project_root, source_ref):
+        # Fallback: maybe we are currently ON the feature branch?
+        # If so, source_ref should be current. But we expect to call this from MAIN.
+        pass
+        
+    if not source_ref:
+         raise RuntimeError(f"Could not determine source branch for Issue {issue_id}. Ensure isolation ref is set.")
+
+    if not git.branch_exists(project_root, source_ref):
+         raise RuntimeError(f"Source branch {source_ref} does not exist.")
+
+    # RE-READ Issue from Source Branch
+    # The 'files' list on main might be outdated. We need the list from the feature branch.
+    relative_path = path.relative_to(project_root)
+    
+    try:
+        # Read file content from git
+        code, access_content, _ = git._run_git(["show", f"{source_ref}:{relative_path}"], project_root)
+        if code == 0:
+            # Parse it
+            # We need to extract yaml frontmatter manually or use existing parser if it supported text input
+            import re
+            import yaml
+            match = re.search(r"^---(.*?)---", access_content, re.DOTALL | re.MULTILINE)
+            if match:
+                data = yaml.safe_load(match.group(1)) or {}
+                source_files = data.get("files", [])
+                if source_files:
+                    # Update issue object with latest files for this operation
+                    issue.files = source_files
+    except Exception as e:
+        # If reading fails (maybe path changed?), we fall back to local 'files'
+        pass
+
+    if not issue.files:
+         return []
+
+    # 1. Conflict Check
+    # A conflict occurs if a file in 'files' has changed on HEAD (main)
+    # since the common ancestor of HEAD and source_ref.
+
+    current_head = git.get_current_branch(project_root)
+    try:
+        base = git.get_merge_base(project_root, current_head, source_ref)
+    except Exception as e:
+        raise RuntimeError(f"Failed to determine merge base: {e}")
+
+    conflicts = []
+    for f in issue.files:
+        # Has main changed this file?
+        if git.has_diff(project_root, base, current_head, [f]):
+            # Has feature also changed this file?
+            if git.has_diff(project_root, base, source_ref, [f]):
+                conflicts.append(f)
+
+    if conflicts:
+        raise RuntimeError(
+            f"Atomic Merge Conflict: The following files changed on both mainline and {issue_id}:\n"
+            + "\n".join([f"  - {f}" for f in conflicts])
+            + "\n\nPlease resolve manually using Cherry-Pick as per AGENTS.md policy."
+        )
+
+    # 2. Perform Atomic Merge (Selective Checkout)
+    try:
+        git.git_checkout_files(project_root, source_ref, issue.files)
+    except Exception as e:
+        raise RuntimeError(f"Selective checkout failed: {e}")
+
+    return issue.files
+
+
 # Resources
 SKILL_CONTENT = """
 ---
@@ -1068,10 +1459,15 @@ def get_resources() -> Dict[str, Any]:
 
 
 def list_issues(
-    issues_root: Path, recursive_workspace: bool = False
+    issues_root: Path, recursive_workspace: bool = False, include_archived: bool = False
 ) -> List[IssueMetadata]:
     """
     List all issues in the project.
+    
+    Args:
+        issues_root: Root directory of issues
+        recursive_workspace: Include issues from workspace members
+        include_archived: Include archived issues (default: False)
     """
     issues = []
     engine = get_engine(str(issues_root.parent))
@@ -1079,7 +1475,11 @@ def list_issues(
 
     for issue_type in all_types:
         base_dir = get_issue_dir(issue_type, issues_root)
-        for status_dir in ["open", "backlog", "closed"]:
+        status_dirs = ["open", "backlog", "closed"]
+        if include_archived:
+            status_dirs.append("archived")
+        
+        for status_dir in status_dirs:
             d = base_dir / status_dir
             if d.exists():
                 for f in d.rglob("*.md"):
@@ -1249,6 +1649,56 @@ def update_issue_content(
             os.unlink(tmp_path)
 
 
+def update_issue_field(
+    issue_path: Path,
+    field: str,
+    value: Any,
+) -> IssueMetadata:
+    """
+    Update a specific field in an issue's frontmatter.
+
+    Args:
+        issue_path: Path to the issue file
+        field: Field name to update
+        value: New value for the field
+
+    Returns:
+        Updated IssueMetadata
+    """
+    # Read full content
+    content = issue_path.read_text()
+
+    # Split Frontmatter and Body
+    match = re.search(r"^---(.*?)---\n(.*)", content, re.DOTALL | re.MULTILINE)
+    if not match:
+        raise ValueError(f"Could not parse frontmatter for {issue_path}")
+
+    yaml_str = match.group(1)
+    body = match.group(2)
+
+    try:
+        data = yaml.safe_load(yaml_str) or {}
+    except yaml.YAMLError as e:
+        raise ValueError(f"Invalid YAML metadata: {e}")
+
+    # Update the field
+    data[field] = value
+    data["updated_at"] = current_time()
+
+    # Serialize back directly (not through model) to preserve all fields
+    yaml_header = yaml.dump(
+        data, sort_keys=False, allow_unicode=True, default_flow_style=False
+    )
+
+    # Reconstruct File
+    new_content = f"---\n{yaml_header}---\n{body}"
+    issue_path.write_text(new_content)
+
+    # Re-hydrate through Model to validate and return
+    updated_meta = IssueMetadata(**data)
+    return updated_meta
+
+
 def generate_delivery_report(
     issues_root: Path, issue_id: str, project_root: Path
 ) -> IssueMetadata:
@@ -1436,10 +1886,15 @@ def check_issue_match(
     return True
 
 
-def search_issues(issues_root: Path, query: str) -> List[IssueMetadata]:
+def search_issues(issues_root: Path, query: str, include_archived: bool = False) -> List[IssueMetadata]:
     """
     Search issues using advanced query syntax.
     Returns list of matching IssueMetadata.
+    
+    Args:
+        issues_root: Root directory of issues
+        query: Search query string
+        include_archived: Include archived issues in search (default: False)
     """
     explicit_positives, terms, negatives = parse_search_query(query)
 
@@ -1449,7 +1904,7 @@ def search_issues(issues_root: Path, query: str) -> List[IssueMetadata]:
     # Let's align with "grep": empty pattern matches everything?
     # Or strict: empty query -> all.
     if not explicit_positives and not terms and not negatives:
-        return list_issues(issues_root)
+        return list_issues(issues_root, include_archived=include_archived)
 
     matches = []
     all_files = []
@@ -1469,7 +1924,11 @@ def search_issues(issues_root: Path, query: str) -> List[IssueMetadata]:
 
     for issue_type in all_types:
         base_dir = get_issue_dir(issue_type, issues_root)
-        for status_dir in ["open", "backlog", "closed"]:
+        status_dirs = ["open", "backlog", "closed"]
+        if include_archived:
+            status_dirs.append("archived")
+        
+        for status_dir in status_dirs:
             d = base_dir / status_dir
             if d.exists():
                 for f in d.rglob("*.md"):