roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/cli/issues/archive.py

@@ -0,0 +1,137 @@
+"""Archive issue command - move completed issues to archive."""
+
+import click
+
+from roadmap.adapters.cli.cli_command_helpers import require_initialized
+from roadmap.adapters.cli.issues.archive_class import IssueArchive
+from roadmap.common.console import get_console
+from roadmap.common.logging import (
+    log_command,
+    verbose_output,
+)
+
+
+@click.command()
+@click.argument("issue_id", required=False)
+@click.option(
+    "--all-closed",
+    is_flag=True,
+    help="Archive all closed issues",
+)
+@click.option(
+    "--orphaned",
+    is_flag=True,
+    help="Archive issues with no milestone assigned",
+)
+@click.option(
+    "--list",
+    "list_archived",
+    is_flag=True,
+    help="List archived issues",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Preview what would be archived without actually doing it",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Skip confirmation prompt",
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Show detailed debug information",
+)
+@click.pass_context
+@verbose_output
+@log_command("issue_archive", entity_type="issue", track_duration=True)
+@require_initialized
+def archive_issue(
+    ctx: click.Context,
+    issue_id: str | None,
+    all_closed: bool,
+    orphaned: bool,
+    list_archived: bool,
+    dry_run: bool,
+    force: bool,
+    verbose: bool,  # noqa: F841
+):
+    """Archive an issue by moving it to .roadmap/archive/issues/.
+
+    This is a non-destructive operation that preserves issue data while
+    cleaning up the active workspace. Archived issues can be restored
+    if needed.
+
+    Examples:
+        roadmap issue archive 8a00a17e
+        roadmap issue archive --all-closed
+        roadmap issue archive --orphaned --dry-run
+        roadmap issue archive --list
+    """
+    core = ctx.obj["core"]
+    console = get_console()
+
+    archive = IssueArchive(core, console)
+
+    if list_archived:
+        # List archived issues
+        from pathlib import Path
+
+        from roadmap.adapters.persistence.parser import IssueParser
+
+        roadmap_dir = Path.cwd() / ".roadmap"
+        archive_dir = roadmap_dir / "archive" / "issues"
+
+        if not archive_dir.exists():
+            console.print("📋 No archived issues.", style="yellow")
+            return
+
+        archived_files = list(archive_dir.rglob("*.md"))
+        if not archived_files:
+            console.print("📋 No archived issues.", style="yellow")
+            return
+
+        console.print("\n📦 Archived Issues:\n", style="bold blue")
+        for file_path in sorted(archived_files):
+            try:
+                issue = IssueParser.parse_issue_file(file_path)
+                milestone = issue.milestone or "No milestone"
+                console.print(
+                    f"  • {issue.id[:8]} - {issue.title} [{milestone}] ({issue.status.value})",
+                    style="cyan",
+                )
+            except Exception:
+                console.print(
+                    f"  • {file_path.name} (error reading file)", style="yellow"
+                )
+        return
+
+    # Validate arguments
+    if not issue_id and not all_closed and not orphaned:
+        console.print(
+            "❌ Error: Specify an issue ID, --all-closed, or --orphaned",
+            style="bold red",
+        )
+        ctx.exit(1)
+
+    if sum([bool(issue_id), all_closed, orphaned]) > 1:
+        console.print(
+            "❌ Error: Specify only one of: issue ID, --all-closed, or --orphaned",
+            style="bold red",
+        )
+        ctx.exit(1)
+
+    try:
+        archive.execute(
+            entity_id=issue_id,
+            all_closed=all_closed,
+            orphaned=orphaned,
+            dry_run=dry_run,
+            force=force,
+        )
+    except Exception as e:
+        console.print(f"❌ Archive operation failed: {str(e)}", style="bold red")
+        ctx.exit(1)

roadmap/adapters/cli/issues/archive_class.py

@@ -0,0 +1,253 @@
+"""IssueArchive command implementation using base class."""
+
+from pathlib import Path
+from typing import Any
+
+from roadmap.adapters.cli.crud import BaseArchive, EntityType
+
+
+class IssueArchive(BaseArchive):
+    """Archive issue command implementation."""
+
+    entity_type = EntityType.ISSUE
+
+    def get_entities_to_archive(
+        self,
+        entity_id: str | None = None,
+        all_closed: bool = False,
+        orphaned: bool = False,
+        **kwargs,
+    ) -> list[Any]:
+        """Get issues to archive based on criteria.
+
+        Args:
+            entity_id: Specific issue ID to archive
+            all_closed: Archive all closed issues
+            orphaned: Archive issues with no milestone
+            **kwargs: Additional arguments
+
+        Returns:
+            List of issues to archive
+        """
+        all_issues = self.core.issues.list()
+
+        if entity_id:
+            issue = self.core.issues.get(entity_id)
+            return [issue] if issue else []
+        elif all_closed:
+            return [i for i in all_issues if i.status.value == "closed"]
+        elif orphaned:
+            return [i for i in all_issues if not i.milestone]
+
+        return []
+
+    def validate_entity_before_archive(
+        self, entity: Any, **kwargs
+    ) -> tuple[bool, str | None]:
+        """Validate issue before archiving.
+
+        Args:
+            entity: The issue to validate
+            **kwargs: Additional arguments (e.g., force flag)
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        # Allow archiving if force flag is set
+        if kwargs.get("force"):
+            return True, None
+
+        if entity.status.value != "closed":
+            return False, f"not closed (status: {entity.status.value})"
+        return True, None
+
+    def find_entity_files(self, entities: list[Any]) -> list[Path]:
+        """Find issue files for entities.
+
+        Args:
+            entities: List of issues
+
+        Returns:
+            List of file paths
+        """
+        roadmap_dir = Path.cwd() / ".roadmap"
+        issues_dir = roadmap_dir / "issues"
+
+        files = []
+        for entity in entities:
+            # Search recursively for issue file by ID prefix
+            matching = list(issues_dir.rglob(f"{str(entity.id)[:8]}*.md"))
+            if matching:
+                files.append(matching[0])
+        return files
+
+    def _determine_archive_path(self, archive_dir: Path, issue_file: Path) -> Path:
+        """Determine archive path preserving folder structure.
+
+        Args:
+            archive_dir: The archive root directory
+            issue_file: The issue file path
+
+        Returns:
+            The destination path for archiving
+        """
+        roadmap_dir = Path.cwd() / ".roadmap"
+        issues_dir = roadmap_dir / "issues"
+
+        try:
+            rel_path = issue_file.relative_to(issues_dir)
+        except ValueError as e:
+            from roadmap.common.logging import get_logger
+
+            logger = get_logger(__name__)
+            logger.debug(
+                "issue_relative_path_failed",
+                file=str(issue_file),
+                error=str(e),
+                action="calculate_archive_path",
+            )
+            return archive_dir / issue_file.name
+
+        # If file is directly in issues_dir (no parent folder), put in archive root
+        if len(rel_path.parts) == 1:
+            return archive_dir / issue_file.name
+
+        # Preserve the parent folder structure
+        dest_dir = archive_dir / rel_path.parent
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        return dest_dir / issue_file.name
+
+    def execute(self, entity_id: str | None = None, **kwargs) -> bool:
+        """Execute archive operation.
+
+        Archives issues by moving files and setting the archived flag.
+
+        Args:
+            entity_id: Optional issue ID
+            **kwargs: Filter options (all_closed, orphaned, etc.)
+
+        Returns:
+            True if successful
+        """
+        try:
+            entities = self.get_entities_to_archive(entity_id, **kwargs)
+
+            if not entities:
+                self.console.print(
+                    f"No {self.entity_type.value}s to archive",
+                    style="yellow",
+                )
+                return False
+
+            # Validate entities
+            invalid_entities = []
+            for entity in entities:
+                is_valid, error_msg = self.validate_entity_before_archive(
+                    entity, **kwargs
+                )
+                if not is_valid:
+                    invalid_entities.append((entity, error_msg))
+                    self.console.print(
+                        f"⚠️  Cannot archive {entity.id}: {error_msg}",
+                        style="yellow",
+                    )
+
+            if invalid_entities:
+                invalid_entity_ids = {e.id for e, _ in invalid_entities}
+                entities = [e for e in entities if e.id not in invalid_entity_ids]
+                if not entities:
+                    return False
+
+            # Find files
+            files_to_archive = self.find_entity_files(entities)
+
+            if not files_to_archive:
+                self.console.print(
+                    f"Could not find files for {len(entities)} {self.entity_type.value}(s)",
+                    style="yellow",
+                )
+                return False
+
+            # Archive with folder structure preservation
+            from roadmap.adapters.cli.crud.crud_helpers import (
+                display_archive_success,
+                get_archive_dir,
+            )
+
+            archive_dir = get_archive_dir(self.entity_type)
+            archive_dir.mkdir(parents=True, exist_ok=True)
+
+            archived_files = []
+            failed_count = 0
+
+            for file_path in files_to_archive:
+                try:
+                    archive_file = self._determine_archive_path(archive_dir, file_path)
+                    if archive_file.exists():
+                        failed_count += 1
+                        continue
+
+                    # Ensure parent directory exists and use rename (mv) for atomicity
+                    archive_file.parent.mkdir(parents=True, exist_ok=True)
+                    file_path.rename(archive_file)
+                    archived_files.append(archive_file)
+
+                except Exception as e:
+                    self.console.print(
+                        f"⚠️  Failed to archive {file_path.name}: {str(e)}",
+                        style="yellow",
+                    )
+                    failed_count += 1
+
+            # Update state (set archived flag and update cache)
+            self.post_archive_hook(archived_files, entities, **kwargs)
+
+            # Display results
+            display_archive_success(
+                self.entity_type,
+                len(archived_files),
+                failed_count,
+                console=self.console,
+            )
+
+            return True
+
+        except Exception as e:
+            self.console.print(
+                f"❌ Archive operation failed: {str(e)}",
+                style="red",
+            )
+            import click
+
+            raise click.ClickException(str(e)) from e
+
+    def post_archive_hook(
+        self, archived_files: list[Path], entities: list[Any], **kwargs
+    ) -> None:
+        """Handle post-archive state updates.
+
+        Sets the archived flag on entities after moving files.
+
+        Args:
+            archived_files: Files that were archived
+            entities: Entities that were archived
+            **kwargs: Additional arguments
+        """
+        # Set archived flag on entities
+        from roadmap.core.models import IssueUpdateServiceParams
+
+        for entity in entities:
+            try:
+                params = IssueUpdateServiceParams(
+                    issue_id=entity.id,
+                    archived=True,
+                )
+                self.core.issues.update_issue(params)
+            except Exception as e:
+                self.console.print(
+                    f"⚠️  Warning: Failed to mark issue {entity.id} as archived: {e}",
+                    style="yellow",
+                )
+
+        # Clear the list cache after archiving to ensure archived issues don't appear in list output
+        self.core.issues._ops.issue_service._list_issues_cache.clear()

roadmap/adapters/cli/issues/block.py

@@ -0,0 +1,39 @@
+"""Block issue command - thin wrapper around update.
+
+This command is syntactic sugar for: roadmap issue update <ID> --status blocked
+"""
+
+import click
+
+from roadmap.adapters.cli.cli_command_helpers import require_initialized
+from roadmap.common.cli_errors import handle_cli_errors
+from roadmap.core.domain import Status
+
+from .issue_status_helpers import StatusChangeConfig, apply_status_change
+
+
+@click.command("block")
+@click.argument("issue_id")
+@click.option("--reason", "-r", help="Reason for blocking")
+@click.pass_context
+@handle_cli_errors(command_name="issue block")
+@require_initialized
+def block_issue(
+    ctx: click.Context,
+    issue_id: str,
+    reason: str,
+):
+    """Mark an issue as blocked (sets status to blocked).
+
+    Syntactic sugar for: roadmap issue update <ID> --status blocked
+    """
+    core = ctx.obj["core"]
+
+    config = StatusChangeConfig(
+        status=Status.BLOCKED,
+        emoji="🚫",
+        title_verb="Blocked",
+        title_style="bold red",
+        status_display="🚫 Blocked",
+    )
+    apply_status_change(core, issue_id, config, reason)

roadmap/adapters/cli/issues/close.py

@@ -0,0 +1,216 @@
+"""Close issue command - thin wrapper around update.
+
+This command is syntactic sugar for: roadmap issue update <ID> --status closed
+
+SEMANTICS:
+- Close: Changes status to 'closed', keeps files in place (no file movement), archived=false
+- Archive: Moves files to archive directory AND sets archived=true flag (signals sync to delete remotely)
+
+This separation allows for flexible status management without workspace reorganization.
+"""
+
+from datetime import UTC, datetime
+
+import click
+from structlog import get_logger
+
+from roadmap.adapters.cli.cli_command_helpers import require_initialized
+from roadmap.adapters.cli.cli_error_handlers import handle_cli_error
+from roadmap.common.console import get_console
+from roadmap.common.formatters.text.operations import (
+    format_operation_failure,
+    format_operation_success,
+)
+from roadmap.common.logging import (
+    log_command,
+    track_database_operation,
+)
+from roadmap.core.domain import Status
+
+console = get_console()
+logger = get_logger()
+
+
+def _parse_completion_date(date_str: str) -> datetime | None:
+    """Parse completion date from string.
+
+    Args:
+        date_str: Date string to parse (YYYY-MM-DD HH:MM or YYYY-MM-DD)
+
+    Returns:
+        Parsed datetime or None if parsing fails
+    """
+    if not date_str:
+        return None
+
+    try:
+        return datetime.strptime(date_str, "%Y-%m-%d %H:%M")
+    except ValueError as e:
+        from roadmap.common.logging import get_logger
+
+        logger = get_logger(__name__)
+        logger.debug(
+            "datetime_parse_failed",
+            date_str=date_str,
+            error=str(e),
+            action="parse_close_date",
+        )
+        try:
+            return datetime.strptime(date_str, "%Y-%m-%d")
+        except ValueError as e:
+            logger.debug(
+                "completion_date_parse_failed", date_str=date_str, error=str(e)
+            )
+            return None
+
+
+def _resolve_end_date(
+    record_time: bool, date: str
+) -> tuple[datetime | None, str | None]:
+    """Resolve completion datetime and validation error message, if any."""
+    if not record_time:
+        return None, None
+
+    if date:
+        end_date = _parse_completion_date(date)
+        if end_date is None:
+            return None, "❌ Invalid date format. Use YYYY-MM-DD or YYYY-MM-DD HH:MM"
+        return end_date, None
+
+    return datetime.now(UTC), None
+
+
+def _build_close_update_kwargs(end_date: datetime | None) -> dict:
+    """Build keyword arguments used for closing an issue."""
+    update_kwargs = {
+        "status": Status.CLOSED,
+        "progress_percentage": 100.0,
+    }
+    if end_date:
+        update_kwargs["actual_end_date"] = end_date
+    return update_kwargs
+
+
+def _build_close_extra_details(
+    updated_issue, reason: str, end_date: datetime | None
+) -> dict[str, str]:
+    """Build success details for close operation output."""
+    extra_details: dict[str, str] = {
+        "Status": "Closed",
+        "Progress": "100%",
+    }
+    if reason:
+        extra_details["Reason"] = reason
+    if not end_date:
+        return extra_details
+
+    extra_details["Completed"] = end_date.strftime("%Y-%m-%d %H:%M")
+    start_date = updated_issue.actual_start_date
+    if not start_date:
+        return extra_details
+
+    duration = end_date - start_date
+    hours = duration.total_seconds() / 3600
+    extra_details["Duration"] = f"{hours:.1f} hours"
+
+    if not updated_issue.estimated_hours:
+        return extra_details
+
+    diff = hours - updated_issue.estimated_hours
+    if abs(diff) <= 0.5:
+        extra_details["Variance"] = "On target"
+    elif diff > 0:
+        extra_details["Variance"] = f"Over by {diff:.1f} hours"
+    else:
+        extra_details["Variance"] = f"Under by {abs(diff):.1f} hours"
+
+    return extra_details
+
+
+@click.command("close")
+@click.argument("issue_id")
+@click.option("--reason", "-r", help="Reason for closing the issue")
+@click.option(
+    "--record-time",
+    "-t",
+    is_flag=True,
+    help="Record actual completion time",
+)
+@click.option(
+    "--date",
+    help="Completion date (YYYY-MM-DD HH:MM, defaults to now)",
+)
+@click.pass_context
+@log_command("issue_close", entity_type="issue", track_duration=True)
+@require_initialized
+def close_issue(
+    ctx: click.Context,
+    issue_id: str,
+    reason: str,
+    record_time: bool,
+    date: str,
+):
+    """Close an issue (sets status to closed and progress to 100%).
+
+    Syntactic sugar for: roadmap issue update <ID> --status closed
+    """
+    core = ctx.obj["core"]
+
+    try:
+        end_date, date_error = _resolve_end_date(record_time, date)
+        if date_error:
+            console.print(date_error, style="bold red")
+            return
+
+        update_kwargs = _build_close_update_kwargs(end_date)
+
+        # Use wrapper for status change display
+        from roadmap.adapters.cli.cli_command_helpers import ensure_entity_exists
+
+        # Verify issue exists before updating
+        ensure_entity_exists(core, "issue", issue_id)
+
+        # Update the issue
+        with track_database_operation(
+            "update", "issue", entity_id=issue_id, warn_threshold_ms=2000
+        ):
+            updated_issue = core.issues.update(issue_id, **update_kwargs)
+
+        if updated_issue:
+            extra_details = _build_close_extra_details(updated_issue, reason, end_date)
+
+            # Use formatter
+            lines = format_operation_success(
+                emoji="✅",
+                action="Closed",
+                entity_title=updated_issue.title,
+                entity_id=issue_id,
+                extra_details=extra_details,
+            )
+            for line in lines:
+                console.print(line, style="bold green" if "Closed" in line else "cyan")
+        else:
+            lines = format_operation_failure(
+                action="close",
+                entity_id=issue_id,
+                error="Failed to update status",
+            )
+            for line in lines:
+                console.print(line, style="bold red")
+
+    except Exception as e:
+        handle_cli_error(
+            error=e,
+            operation="close_issue",
+            entity_type="issue",
+            entity_id=issue_id,
+            context={"reason": reason},
+            fatal=True,
+        )
+        lines = format_operation_failure(
+            action="close",
+            entity_id=issue_id,
+            error=str(e),
+        )
+        for line in lines:
+            console.print(line, style="bold red")