roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/domain/issue.py

@@ -0,0 +1,274 @@
+"""Issue domain model."""
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, Field, PrivateAttr, model_validator
+
+from roadmap.common.constants import IssueType, Priority, Status
+from roadmap.core.domain.comment import Comment
+
+
+def now_utc():
+    """Get current UTC datetime with timezone awareness."""
+    from roadmap.common.utils.timezone_utils import now_utc as tz_now_utc
+
+    return tz_now_utc()
+
+
+class Issue(BaseModel):
+    """Issue data model."""
+
+    model_config = {"ser_json_timedelta": "float"}
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4())[:8])
+    title: str
+    headline: str = ""  # Short summary for list views
+    priority: Priority = Priority.MEDIUM
+    status: Status = Status.TODO
+    archived: bool = False  # Mark for remote deletion
+    issue_type: IssueType = IssueType.OTHER
+    milestone: str | None = None
+    labels: list[str] = Field(default_factory=list)
+    remote_ids: dict[str, str | int] = Field(
+        default_factory=dict,
+        description="Remote issue IDs keyed by backend name (e.g., {'github': 42, 'gitlab': 123})",
+    )
+    created: datetime = Field(default_factory=now_utc)
+    updated: datetime = Field(default_factory=now_utc)
+    assignee: str | None = None
+    content: str = ""  # Markdown content
+    estimated_hours: float | None = None  # Estimated time to complete in hours
+    due_date: datetime | None = None  # When the issue should be completed
+    depends_on: list[str] = Field(
+        default_factory=list
+    )  # List of issue IDs this depends on
+    blocks: list[str] = Field(default_factory=list)  # List of issue IDs this blocks
+    actual_start_date: datetime | None = None  # When work actually started
+    actual_end_date: datetime | None = None  # When work was completed
+    progress_percentage: float | None = None  # Progress from 0.0 to 100.0
+    handoff_notes: str | None = None  # Notes for task handoff
+    previous_assignee: str | None = None  # Who was previously assigned
+    handoff_date: datetime | None = None  # When the task was handed off
+    git_branches: list[str] = Field(
+        default_factory=list
+    )  # Git branches linked to this issue
+    git_commits: list[dict[str, Any]] = Field(
+        default_factory=list
+    )  # Git commits referencing this issue
+    completed_date: str | None = None  # ISO string when issue was completed via Git
+    comments: list[Comment] = Field(
+        default_factory=list
+    )  # Comments on this issue for discussion
+    file_path: str | None = Field(
+        default=None, exclude=True
+    )  # Internal: absolute path where issue file is stored
+    github_sync_metadata: dict[str, Any] | None = Field(
+        default=None, exclude=True
+    )  # Internal: sync metadata tracking for GitHub integration
+
+    _modified: bool = PrivateAttr(default=False)
+    _local_changes: dict[str, Any] | None = PrivateAttr(default=None)
+
+    @model_validator(mode="before")
+    @classmethod
+    def migrate_github_issue_to_remote_ids(cls, data: Any) -> Any:
+        """Migrate legacy github_issue field to remote_ids dict.
+
+        Handles loading old YAML files that have github_issue field.
+        Validates and converts to proper types (string numbers to int).
+        """
+        if isinstance(data, dict) and "github_issue" in data:
+            github_issue = data.pop("github_issue")
+            if github_issue is not None:
+                # Initialize remote_ids if not present
+                if "remote_ids" not in data:
+                    data["remote_ids"] = {}
+
+                # Convert string to int if needed
+                if isinstance(github_issue, str):
+                    if not github_issue.isdigit():
+                        raise ValueError(
+                            "github_issue: must be an integer or numeric string"
+                        )
+                    github_issue = int(github_issue)
+                elif not isinstance(github_issue, int):
+                    raise ValueError("github_issue: must be an integer")
+
+                # Validate positive
+                if github_issue <= 0:
+                    raise ValueError("github_issue: must be a positive integer")
+
+                # Migrate github_issue to remote_ids
+                data["remote_ids"]["github"] = github_issue
+        return data
+
+    @property
+    def github_issue(self) -> int | str | None:
+        """Get GitHub issue ID from remote_ids dict.
+
+        Provides backwards compatibility for code accessing issue.github_issue.
+        """
+        if self.remote_ids and "github" in self.remote_ids:
+            return self.remote_ids["github"]
+        return None
+
+    @github_issue.setter
+    def github_issue(self, value: int | str | None) -> None:
+        """Set GitHub issue ID in remote_ids dict.
+
+        Provides backwards compatibility for code setting issue.github_issue.
+        Validates that the value is a positive integer.
+        """
+        if value is None:
+            # Remove github key if setting to None
+            if self.remote_ids and "github" in self.remote_ids:
+                del self.remote_ids["github"]
+        else:
+            # Convert string to int and validate
+            if isinstance(value, str):
+                if not value.isdigit():
+                    raise ValueError(
+                        "github_issue: must be an integer or numeric string"
+                    )
+                value = int(value)
+            elif not isinstance(value, int):
+                raise ValueError("github_issue: must be an integer or numeric string")
+
+            if value <= 0:
+                raise ValueError("github_issue: must be a positive integer")
+
+            if not self.remote_ids:
+                self.remote_ids = {}
+            self.remote_ids["github"] = value
+
+    def model_dump(self, **kwargs) -> dict[str, Any]:
+        """Override model_dump to properly serialize remote_ids and github_issue.
+
+        Includes github_issue for backwards compatibility in API/JSON usage.
+        For file serialization (YAML), callers should remove github_issue field
+        to ensure files use the modern remote_ids format.
+        """
+        data = super().model_dump(**kwargs)
+
+        # Add github_issue for backwards compatibility in API responses
+        # Callers handling file serialization should remove this field
+        data["github_issue"] = self.github_issue
+
+        return data
+
+    def model_dump_json(self, **kwargs) -> str:
+        """Override model_dump_json to include github_issue property for backwards compatibility."""
+        # Get the dumped data which already includes github_issue via model_dump
+        data = self.model_dump()
+        # Use JSON serialization
+        import json
+
+        return json.dumps(data, default=str)
+
+    @property
+    def is_backlog(self) -> bool:
+        """Check if this issue is in the backlog (no milestone assigned)."""
+        return self.milestone is None or self.milestone == ""
+
+    @property
+    def milestone_name(self) -> str:
+        """Get the milestone name or 'Backlog' if none assigned."""
+        return self.milestone if self.milestone else "Backlog"
+
+    @property
+    def estimated_time_display(self) -> str:
+        """Get a human-readable display of estimated time."""
+        if self.estimated_hours is None:
+            return "Not estimated"
+
+        if self.estimated_hours < 1:
+            minutes = int(self.estimated_hours * 60)
+            return f"{minutes}m"
+        elif self.estimated_hours < 8:
+            return f"{self.estimated_hours:.1f}h"
+        else:
+            days = self.estimated_hours / 8  # Assuming 8-hour work days
+            return f"{days:.1f}d"
+
+    @property
+    def is_started(self) -> bool:
+        """Check if work has actually started on this issue."""
+        return self.actual_start_date is not None
+
+    @property
+    def is_completed(self) -> bool:
+        """Check if work has been completed on this issue."""
+        return self.actual_end_date is not None
+
+    @property
+    def progress_display(self) -> str:
+        """Get a human-readable display of progress as percentage (0-100%).
+
+        Returns:
+            - Empty string for Todo (not yet started)
+            - "100%" for Closed
+            - Explicit percentage if set
+            - "0%" for other statuses (in-progress, blocked, review) when no explicit progress
+        """
+        if self.progress_percentage is not None:
+            return f"{self.progress_percentage:.0f}%"
+
+        # Infer progress from status when not explicitly set
+        if self.status == Status.CLOSED:
+            return "100%"
+        elif self.status == Status.TODO:
+            return ""  # Blank for todo - no progress tracking yet
+        else:
+            # For in-progress, blocked, review - default to 0% if no explicit progress
+            return "0%"
+
+    @property
+    def actual_duration_hours(self) -> float | None:
+        """Calculate actual duration if both start and end dates are set."""
+        if self.actual_start_date and self.actual_end_date:
+            delta = self.actual_end_date - self.actual_start_date
+            return delta.total_seconds() / 3600  # Convert to hours
+        return None
+
+    @property
+    def is_overdue(self) -> bool:
+        """Check if the issue is overdue based on estimates and actual start."""
+        if not self.actual_start_date or not self.estimated_hours:
+            return False
+
+        if self.actual_end_date:
+            # Already completed, check if it took longer than estimated
+            actual_hours = self.actual_duration_hours
+            return bool(actual_hours and actual_hours > self.estimated_hours)
+
+        # Still in progress, check if it's taking longer than estimated
+        elapsed = datetime.now(UTC) - self.actual_start_date
+        elapsed_hours = elapsed.total_seconds() / 3600
+        return elapsed_hours > self.estimated_hours
+
+    @property
+    def has_been_handed_off(self) -> bool:
+        """Check if this issue has been handed off to another person."""
+        return self.previous_assignee is not None and self.handoff_date is not None
+
+    @property
+    def handoff_context_summary(self) -> str:
+        """Get a summary of handoff context for display."""
+        if not self.has_been_handed_off:
+            return "No previous handoff"
+
+        if self.handoff_notes:
+            return f"From {self.previous_assignee}: {self.handoff_notes[:100]}..."
+        else:
+            return f"Handed off from {self.previous_assignee}"
+
+    @property
+    def filename(self) -> str:
+        """Generate filename for this issue."""
+        safe_title = "".join(
+            c for c in self.title if c.isalnum() or c in (" ", "-", "_")
+        ).strip()
+        safe_title = safe_title.replace(" ", "-").lower()
+        return f"{self.id}-{safe_title}.md"

roadmap/core/domain/milestone.py

@@ -0,0 +1,173 @@
+"""Milestone domain model."""
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, Field
+
+from roadmap.common.constants import MilestoneStatus, RiskLevel, Status
+
+from .comment import Comment
+
+# Import timezone utilities with circular import protection
+try:
+    from roadmap.common.utils.timezone_utils import now_utc
+except ImportError:
+    # Fallback during module loading
+    def now_utc() -> datetime:
+        """Get current UTC datetime.
+
+        Returns:
+            Current datetime in UTC timezone.
+        """
+        return datetime.now(UTC)
+
+
+class Milestone(BaseModel):
+    """Milestone data model."""
+
+    name: str
+    headline: str = ""  # Short summary for list views
+    content: str = ""  # Markdown content
+    due_date: datetime | None = None
+    status: MilestoneStatus = MilestoneStatus.OPEN
+    archived: bool = False  # Mark for remote deletion
+    github_milestone: int | None = None
+    created: datetime = Field(default_factory=now_utc)
+    updated: datetime = Field(default_factory=now_utc)
+    project_id: str | None = (
+        None  # Project this milestone belongs to (for relationship tracking)
+    )
+
+    # Automatic progress tracking fields
+    calculated_progress: float | None = None  # Auto-calculated from issues
+    last_progress_update: datetime | None = None
+    completion_velocity: float | None = None  # Issues/week
+    risk_level: RiskLevel = RiskLevel.LOW
+    actual_start_date: datetime | None = None
+    actual_end_date: datetime | None = None
+    comments: list[Comment] = Field(
+        default_factory=list
+    )  # Comments on this milestone for discussion
+
+    file_path: str | None = Field(
+        default=None, exclude=True
+    )  # Internal: absolute path where milestone file is stored
+
+    def get_issues(self, all_issues):
+        """Get all issues assigned to this milestone.
+
+        Args:
+            all_issues: List of Issue objects to filter
+
+        Returns:
+            List of issues assigned to this milestone
+        """
+        return [issue for issue in all_issues if issue.milestone == self.name]
+
+    def get_issue_count(self, all_issues):
+        """Get the count of issues assigned to this milestone."""
+        return len(self.get_issues(all_issues))
+
+    def get_completion_percentage(
+        self, all_issues, method: str = "effort_weighted"
+    ) -> float:
+        """Get the completion percentage of this milestone.
+
+        Args:
+            all_issues: List of all issues in the system
+            method: 'effort_weighted' or 'count_based'
+
+        Returns:
+            Completion percentage from 0.0 to 100.0
+        """
+        milestone_issues = self.get_issues(all_issues)
+        if not milestone_issues:
+            return 0.0
+
+        if method == "count_based":
+            # Simple count-based calculation
+            completed_issues = [
+                issue for issue in milestone_issues if issue.status == Status.CLOSED
+            ]
+            return (len(completed_issues) / len(milestone_issues)) * 100.0
+        else:
+            # Effort-weighted calculation (preferred)
+            total_effort = 0.0
+            completed_effort = 0.0
+
+            for issue in milestone_issues:
+                effort = (
+                    issue.estimated_hours or 1.0
+                )  # Default to 1 hour if not estimated
+                total_effort += effort
+
+                if issue.status == Status.CLOSED:
+                    completed_effort += effort
+                elif issue.progress_percentage is not None:
+                    # Partial completion based on progress percentage
+                    completed_effort += effort * (issue.progress_percentage / 100.0)
+
+            return (
+                (completed_effort / total_effort) * 100.0 if total_effort > 0 else 0.0
+            )
+
+    def get_total_estimated_hours(self, all_issues) -> float:
+        """Get the total estimated hours for all issues in this milestone."""
+        milestone_issues = self.get_issues(all_issues)
+        total_hours = 0.0
+        for issue in milestone_issues:
+            if issue.estimated_hours is not None:
+                total_hours += issue.estimated_hours
+        return total_hours
+
+    def get_remaining_estimated_hours(self, all_issues) -> float:
+        """Get the remaining estimated hours for incomplete issues in this milestone."""
+        milestone_issues = self.get_issues(all_issues)
+        remaining_hours = 0.0
+        for issue in milestone_issues:
+            if issue.status != Status.CLOSED and issue.estimated_hours is not None:
+                remaining_hours += issue.estimated_hours
+        return remaining_hours
+
+    def get_estimated_time_display(self, all_issues) -> str:
+        """Get a human-readable display of total estimated time."""
+        total_hours = self.get_total_estimated_hours(all_issues)
+        if total_hours == 0:
+            return "Not estimated"
+
+        if total_hours < 8:
+            return f"{total_hours:.1f}h"
+        else:
+            days = total_hours / 8  # Assuming 8-hour work days
+            return f"{days:.1f}d"
+
+    def update_automatic_fields(
+        self, all_issues, method: str = "effort_weighted"
+    ) -> None:
+        """Update all automatic progress tracking fields.
+
+        Args:
+            all_issues: List of all issues in the system
+            method: Calculation method ('effort_weighted' or 'count_based')
+        """
+        self.calculated_progress = self.get_completion_percentage(all_issues, method)
+        self.last_progress_update = datetime.now(UTC)
+        self.updated = datetime.now(UTC)
+
+        # Update status based on progress
+        if self.calculated_progress >= 100.0:
+            self.status = MilestoneStatus.CLOSED
+            if not self.actual_end_date:
+                self.actual_end_date = datetime.now(UTC)
+        elif self.calculated_progress > 0:
+            if self.status == MilestoneStatus.OPEN and not self.actual_start_date:
+                self.actual_start_date = datetime.now(UTC)
+
+    @property
+    def filename(self) -> str:
+        """Generate filename for this milestone."""
+        safe_name = "".join(
+            c for c in self.name if c.isalnum() or c in (" ", "-", "_")
+        ).strip()
+        safe_name = safe_name.replace(" ", "-").lower()
+        return f"{safe_name}.md"

roadmap/core/domain/ports/__init__.py

@@ -0,0 +1 @@
+"""Port interfaces for domain layer."""

roadmap/core/domain/ports/baseline_repository.py

@@ -0,0 +1,24 @@
+"""Port for managing baseline state (canonical sync point)."""
+
+from abc import ABC, abstractmethod
+
+from roadmap.core.services.sync.sync_state import SyncState
+
+
+class IBaselineRepository(ABC):
+    """Port for managing baseline state (canonical sync point)."""
+
+    @abstractmethod
+    def load(self) -> SyncState | None:
+        """Load current baseline. Returns None if not set."""
+        pass
+
+    @abstractmethod
+    def save(self, baseline: SyncState) -> None:
+        """Save baseline state."""
+        pass
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Clear baseline (reset sync state)."""
+        pass

roadmap/core/domain/ports/issue_repository.py

@@ -0,0 +1,34 @@
+"""Port for reading/writing issues to persistent storage."""
+
+from abc import ABC, abstractmethod
+
+from roadmap.core.domain.issue import Issue
+
+
+class IIssueRepository(ABC):
+    """Port for reading/writing issues to persistent storage."""
+
+    @abstractmethod
+    def get_all(self) -> list[Issue]:
+        """Get all issues including archived."""
+        pass
+
+    @abstractmethod
+    def get(self, issue_id: str) -> Issue:
+        """Get single issue by ID. Raises IssueNotFound."""
+        pass
+
+    @abstractmethod
+    def save(self, issue: Issue) -> None:
+        """Save or update an issue."""
+        pass
+
+    @abstractmethod
+    def delete(self, issue_id: str) -> None:
+        """Permanently delete an issue."""
+        pass
+
+    @abstractmethod
+    def archive(self, issue_id: str) -> None:
+        """Archive an issue (mark state=archived)."""
+        pass

roadmap/core/domain/ports/remote_backend_port.py

@@ -0,0 +1,31 @@
+"""Port for communicating with remote systems (GitHub, etc)."""
+
+from abc import ABC, abstractmethod
+
+from roadmap.common.result import Result
+from roadmap.core.models.sync_models import SyncIssue
+from roadmap.core.services.sync.sync_errors import SyncError
+
+
+class IRemoteBackendPort(ABC):
+    """Port for communicating with remote systems (GitHub, etc)."""
+
+    @abstractmethod
+    def authenticate(self) -> Result[None, SyncError]:
+        """Authenticate with remote backend. Returns Ok(None) or Err."""
+        pass
+
+    @abstractmethod
+    def get_issues(self) -> Result[dict[str, SyncIssue], SyncError]:
+        """Fetch all remote issues. Key is issue ID, value is SyncIssue."""
+        pass
+
+    @abstractmethod
+    def push_issue(self, issue_id: str, _payload: dict) -> Result[None, SyncError]:
+        """Push local issue to remote."""
+        pass
+
+    @abstractmethod
+    def pull_issue(self, remote_id: str) -> Result[SyncIssue, SyncError]:
+        """Pull single remote issue."""
+        pass

roadmap/core/domain/project.py

@@ -0,0 +1,130 @@
+"""Project domain model."""
+
+import uuid
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, Field
+
+from roadmap.common.constants import Priority, ProjectStatus
+
+from .comment import Comment
+from .milestone import MilestoneStatus, RiskLevel
+
+
+class Project(BaseModel):
+    """Project data model."""
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4())[:8])
+    name: str
+    headline: str = ""  # Short summary for list views
+    content: str = ""  # Markdown content
+    status: ProjectStatus = ProjectStatus.PLANNING
+    priority: Priority = Priority.MEDIUM
+    owner: str | None = None
+    start_date: datetime | None = None
+    target_end_date: datetime | None = None
+    actual_end_date: datetime | None = None
+    created: datetime = Field(default_factory=datetime.now)
+    updated: datetime = Field(default_factory=datetime.now)
+    milestones: list[str] = Field(default_factory=list)  # List of milestone names
+    estimated_hours: float | None = None
+    actual_hours: float | None = None
+    repo_url: str | None = (
+        None  # URL to the repository (for context/future cross-repo tooling)
+    )
+
+    # Automatic progress tracking fields
+    calculated_progress: float | None = None  # Auto-calculated from milestones
+    last_progress_update: datetime | None = None
+    projected_end_date: datetime | None = None  # Auto-calculated
+    schedule_variance: int | None = None  # Days ahead/behind
+    completion_velocity: float | None = None  # Milestones/week
+    risk_level: RiskLevel = RiskLevel.LOW
+    comments: list[Comment] = Field(
+        default_factory=list
+    )  # Comments on this project for discussion
+
+    file_path: str | None = Field(
+        default=None, exclude=True
+    )  # Internal: absolute path where project file is stored
+
+    def get_milestones(self, all_milestones):
+        """Get all milestones assigned to this project.
+
+        Args:
+            all_milestones: List of Milestone objects to filter
+
+        Returns:
+            List of milestones assigned to this project
+        """
+        return [
+            milestone
+            for milestone in all_milestones
+            if milestone.name in self.milestones
+        ]
+
+    def get_milestone_count(self, all_milestones) -> int:
+        """Get the count of milestones assigned to this project."""
+        return len(self.get_milestones(all_milestones))
+
+    def calculate_progress(self, all_milestones, all_issues) -> float:
+        """Calculate project progress from milestone completion (effort-weighted).
+
+        Args:
+            all_milestones: List of all milestones in the system
+            all_issues: List of all issues in the system
+
+        Returns:
+            Progress percentage from 0.0 to 100.0
+        """
+        project_milestones = self.get_milestones(all_milestones)
+        if not project_milestones:
+            return 0.0
+
+        # Use milestone effort (total estimated hours) as weight
+        total_weight = 0.0
+        completed_weight = 0.0
+
+        for milestone in project_milestones:
+            milestone_weight = milestone.get_total_estimated_hours(all_issues) or 1.0
+            total_weight += milestone_weight
+
+            if milestone.status == MilestoneStatus.CLOSED:
+                completed_weight += milestone_weight
+            else:
+                # Partial completion based on milestone progress
+                milestone_progress = (
+                    milestone.get_completion_percentage(all_issues) / 100.0
+                )
+                completed_weight += milestone_weight * milestone_progress
+
+        return (completed_weight / total_weight) * 100.0 if total_weight > 0 else 0.0
+
+    def update_automatic_fields(self, all_milestones, all_issues) -> None:
+        """Update all automatic progress tracking fields.
+
+        Args:
+            all_milestones: List of all milestones in the system
+            all_issues: List of all issues in the system
+        """
+        self.calculated_progress = self.calculate_progress(all_milestones, all_issues)
+        self.last_progress_update = datetime.now(UTC)
+        self.updated = datetime.now(UTC)
+
+        # Update status based on progress
+        if self.calculated_progress >= 100.0:
+            self.status = ProjectStatus.COMPLETED
+            if not self.actual_end_date:
+                self.actual_end_date = datetime.now(UTC)
+        elif self.calculated_progress > 0:
+            if self.status == ProjectStatus.PLANNING:
+                self.status = ProjectStatus.ACTIVE
+
+    @property
+    def filename(self) -> str:
+        """Generate filename for this project."""
+        safe_name = "".join(
+            c for c in self.name if c.isalnum() or c in (" ", "-", "_")
+        ).strip()
+        safe_name = safe_name.replace(" ", "-").lower()
+        return f"{self.id}-{safe_name}.md"