solokit 0.1.1__py3-none-any.whl

solokit/session/briefing/orchestrator.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+Session briefing orchestrator.
+Coordinates all briefing components to generate comprehensive session briefings.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from solokit.core.exceptions import GitError, SystemError
+from solokit.core.logging_config import get_logger
+
+from .documentation_loader import DocumentationLoader
+from .formatter import BriefingFormatter
+from .git_context import GitContext
+from .learning_loader import LearningLoader
+from .milestone_builder import MilestoneBuilder
+from .stack_detector import StackDetector
+from .tree_generator import TreeGenerator
+from .work_item_loader import WorkItemLoader
+
+logger = get_logger(__name__)
+
+
+class SessionBriefing:
+    """Orchestrate generation of comprehensive session briefings."""
+
+    def __init__(
+        self,
+        session_dir: Path | None = None,
+        project_root: Path | None = None,
+    ):
+        """Initialize session briefing orchestrator.
+
+        Args:
+            session_dir: Path to .session directory (defaults to .session)
+            project_root: Path to project root (defaults to current directory)
+        """
+        self.session_dir = session_dir or Path(".session")
+        self.project_root = project_root or Path.cwd()
+
+        # Initialize all component modules
+        self.work_item_loader = WorkItemLoader(session_dir=self.session_dir)
+        self.learning_loader = LearningLoader(session_dir=self.session_dir)
+        self.doc_loader = DocumentationLoader(project_root=self.project_root)
+        self.stack_detector = StackDetector(session_dir=self.session_dir)
+        self.tree_generator = TreeGenerator(session_dir=self.session_dir)
+        self.git_context = GitContext()
+        self.milestone_builder = MilestoneBuilder(session_dir=self.session_dir)
+        self.formatter = BriefingFormatter()
+
+    def generate_briefing(self, item_id: str, item: dict, learnings_data: dict) -> str:
+        """Generate comprehensive markdown briefing with full project context.
+
+        Args:
+            item_id: Work item identifier
+            item: Work item dictionary
+            learnings_data: Full learnings data structure
+
+        Returns:
+            Complete briefing as markdown string
+        """
+        # Load all context using specialized modules
+        project_docs = self.doc_loader.load_project_docs()
+        current_stack = self.stack_detector.load_current_stack()
+        current_tree = self.tree_generator.load_current_tree()
+        work_item_spec = self.work_item_loader.load_work_item_spec(item)
+        env_checks = self.formatter.validate_environment()
+
+        # Check git status - gracefully handle errors as this is informational
+        try:
+            git_status = self.git_context.check_git_status()
+        except (GitError, SystemError) as e:
+            logger.warning(f"Failed to check git status: {e.message}")
+            git_status = {"clean": False, "status": f"Error: {e.message}", "branch": None}
+
+        # Validate spec completeness
+        spec_validation_warning = self._validate_spec(item_id, item["type"])
+
+        # Get milestone context
+        milestone_context = self.milestone_builder.load_milestone_context(item)
+
+        # Get relevant learnings
+        relevant_learnings = self.learning_loader.get_relevant_learnings(
+            learnings_data, item, work_item_spec
+        )
+
+        # Generate briefing using formatter
+        return self.formatter.generate_briefing(
+            item_id=item_id,
+            item=item,
+            project_docs=project_docs,
+            current_stack=current_stack,
+            current_tree=current_tree,
+            work_item_spec=work_item_spec,
+            env_checks=env_checks,
+            git_status=git_status,
+            spec_validation_warning=spec_validation_warning,
+            milestone_context=milestone_context,
+            relevant_learnings=relevant_learnings,
+        )
+
+    def _validate_spec(self, item_id: str, work_item_type: str) -> str | None:
+        """Validate spec completeness and return warning if incomplete.
+
+        Args:
+            item_id: Work item identifier
+            work_item_type: Type of work item
+
+        Returns:
+            Validation warning string or None if valid
+        """
+        try:
+            from solokit.core.exceptions import FileNotFoundError as SolokitFileNotFoundError
+            from solokit.core.exceptions import SpecValidationError
+            from solokit.work_items.spec_validator import (
+                format_validation_report,
+                validate_spec_file,
+            )
+
+            try:
+                validate_spec_file(item_id, work_item_type)
+                # If no exception, spec is valid
+                return None
+            except SpecValidationError as e:
+                # Spec has validation errors
+                return format_validation_report(item_id, work_item_type, e)
+            except (SolokitFileNotFoundError, Exception):
+                # Spec file doesn't exist or other error - this is not critical for briefing
+                # Just return None and let the briefing proceed
+                return None
+        except ImportError:
+            # Gracefully handle if spec_validator not available
+            logger.debug("Spec validator not available")
+
+        return None

solokit/session/briefing/stack_detector.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""
+Technology stack detection and information loading.
+Part of the briefing module decomposition.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from solokit.core.error_handlers import log_errors
+from solokit.core.exceptions import FileOperationError
+from solokit.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class StackDetector:
+    """Detect and load technology stack information."""
+
+    def __init__(self, session_dir: Path | None = None):
+        """Initialize stack detector.
+
+        Args:
+            session_dir: Path to .session directory (defaults to .session)
+        """
+        self.session_dir = session_dir or Path(".session")
+        self.stack_file = self.session_dir / "tracking" / "stack.txt"
+
+    @log_errors()
+    def load_current_stack(self) -> str:
+        """Load current technology stack.
+
+        Returns:
+            Stack information as string
+
+        Raises:
+            FileOperationError: If stack file exists but cannot be read
+        """
+        if not self.stack_file.exists():
+            return "Stack not yet generated"
+
+        try:
+            return self.stack_file.read_text()
+        except OSError as e:
+            raise FileOperationError(
+                operation="read",
+                file_path=str(self.stack_file),
+                details=f"Failed to read stack file: {e}",
+                cause=e,
+            ) from e

solokit/session/briefing/tree_generator.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""
+Project directory tree loading.
+Part of the briefing module decomposition.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from solokit.core.error_handlers import log_errors
+from solokit.core.exceptions import FileOperationError
+from solokit.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class TreeGenerator:
+    """Load and generate project directory tree."""
+
+    def __init__(self, session_dir: Path | None = None):
+        """Initialize tree generator.
+
+        Args:
+            session_dir: Path to .session directory (defaults to .session)
+        """
+        self.session_dir = session_dir or Path(".session")
+        self.tree_file = self.session_dir / "tracking" / "tree.txt"
+
+    @log_errors()
+    def load_current_tree(self) -> str:
+        """Load current project structure.
+
+        Returns:
+            Project tree as string
+
+        Raises:
+            FileOperationError: If tree file exists but cannot be read
+        """
+        if not self.tree_file.exists():
+            return "Tree not yet generated"
+
+        try:
+            # Return full tree
+            return self.tree_file.read_text()
+        except OSError as e:
+            raise FileOperationError(
+                operation="read",
+                file_path=str(self.tree_file),
+                details=f"Failed to read tree file: {e}",
+                cause=e,
+            ) from e

solokit/session/briefing/work_item_loader.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""
+Work item loading and dependency resolution.
+Part of the briefing module decomposition.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from solokit.core.logging_config import get_logger
+from solokit.core.types import Priority, WorkItemStatus
+
+logger = get_logger(__name__)
+
+
+class WorkItemLoader:
+    """Load work items and their dependencies."""
+
+    def __init__(self, session_dir: Path | None = None):
+        """Initialize work item loader.
+
+        Args:
+            session_dir: Path to .session directory (defaults to .session)
+        """
+        self.session_dir = session_dir or Path(".session")
+        self.work_items_file = self.session_dir / "tracking" / "work_items.json"
+
+    def load_work_items(self) -> dict[str, Any]:
+        """Load work items from tracking file.
+
+        Returns:
+            Work items data structure with 'work_items' dict
+        """
+        logger.debug("Loading work items from: %s", self.work_items_file)
+        if not self.work_items_file.exists():
+            logger.warning("Work items file not found: %s", self.work_items_file)
+            return {"work_items": {}}
+        with open(self.work_items_file) as f:
+            return json.load(f)  # type: ignore[no-any-return]
+
+    def get_work_item(
+        self, work_item_id: str, work_items_data: dict[str, Any] | None = None
+    ) -> dict[str, Any] | None:
+        """Get a specific work item by ID.
+
+        Args:
+            work_item_id: Work item identifier
+            work_items_data: Pre-loaded work items data (optional)
+
+        Returns:
+            Work item dict or None if not found
+        """
+        if work_items_data is None:
+            work_items_data = self.load_work_items()
+
+        return work_items_data.get("work_items", {}).get(work_item_id)  # type: ignore[no-any-return]
+
+    def get_next_work_item(self, work_items_data: dict) -> tuple[str | None, dict | None]:
+        """Find next available work item where dependencies are satisfied.
+
+        Prioritizes resuming in-progress items over starting new work.
+        Returns item with highest priority among available.
+
+        Args:
+            work_items_data: Loaded work items data structure
+
+        Returns:
+            Tuple of (item_id, item) or (None, None) if no work available
+        """
+        work_items = work_items_data.get("work_items", {})
+        priority_order = {
+            Priority.CRITICAL.value: 4,
+            Priority.HIGH.value: 3,
+            Priority.MEDIUM.value: 2,
+            Priority.LOW.value: 1,
+        }
+
+        # PRIORITY 1: Resume in-progress work
+        in_progress_items = []
+        for item_id, item in work_items.items():
+            if item["status"] == WorkItemStatus.IN_PROGRESS.value:
+                in_progress_items.append((item_id, item))
+
+        if in_progress_items:
+            # Sort by priority and return highest
+            in_progress_items.sort(
+                key=lambda x: priority_order.get(x[1].get("priority", Priority.MEDIUM.value), 2),
+                reverse=True,
+            )
+            return in_progress_items[0]
+
+        # PRIORITY 2: Start new work
+        available = []
+        for item_id, item in work_items.items():
+            if item["status"] != WorkItemStatus.NOT_STARTED.value:
+                continue
+
+            # Check dependencies
+            deps_satisfied = all(
+                work_items.get(dep_id, {}).get("status") == WorkItemStatus.COMPLETED.value
+                for dep_id in item.get("dependencies", [])
+            )
+
+            if deps_satisfied:
+                available.append((item_id, item))
+
+        if not available:
+            return None, None
+
+        # Sort by priority
+        available.sort(
+            key=lambda x: priority_order.get(x[1].get("priority", Priority.MEDIUM.value), 2),
+            reverse=True,
+        )
+
+        return available[0]
+
+    def load_work_item_spec(self, work_item: str | dict[str, Any]) -> str:
+        """Load work item specification file.
+
+        Args:
+            work_item: Either a work item dict with 'spec_file' and 'id' fields,
+                      or a string work_item_id (for backwards compatibility)
+
+        Returns:
+            Specification content as string
+        """
+        # Handle backwards compatibility: accept both dict and string
+        if isinstance(work_item, str):
+            # Legacy call with just work_item_id string
+            work_item_id = work_item
+            spec_file = self.session_dir / "specs" / f"{work_item_id}.md"
+        else:
+            # New call with work item dict
+            # Use spec_file from work item if available, otherwise fallback to ID-based pattern
+            spec_file_path = work_item.get("spec_file")
+            if spec_file_path:
+                spec_file = Path(spec_file_path)
+            else:
+                # Fallback to legacy pattern for backwards compatibility
+                work_item_id_raw = work_item.get("id")
+                if not work_item_id_raw:
+                    return "Specification file not found: work item has no id"
+                spec_file = self.session_dir / "specs" / f"{work_item_id_raw}.md"
+
+        if spec_file.exists():
+            return spec_file.read_text()
+        return f"Specification file not found: {spec_file}"
+
+    def update_work_item_status(
+        self, work_item_id: str, status: str, session_num: int | None = None
+    ) -> bool:
+        """Update work item status and optionally add session tracking.
+
+        Args:
+            work_item_id: Work item identifier
+            status: New status value
+            session_num: Optional session number to add to tracking
+
+        Returns:
+            True if update successful, False otherwise
+        """
+        if not self.work_items_file.exists():
+            logger.error("Work items file not found: %s", self.work_items_file)
+            return False
+
+        with open(self.work_items_file) as f:
+            work_items_data = json.load(f)
+
+        if work_item_id not in work_items_data["work_items"]:
+            logger.error("Work item not found: %s", work_item_id)
+            return False
+
+        work_item = work_items_data["work_items"][work_item_id]
+        work_item["status"] = status
+        work_item["updated_at"] = datetime.now().isoformat()
+
+        # Add session tracking if session_num provided
+        if session_num is not None:
+            if "sessions" not in work_item:
+                work_item["sessions"] = []
+            work_item["sessions"].append(
+                {"session_num": session_num, "started_at": datetime.now().isoformat()}
+            )
+
+        # Update metadata counters
+        work_items = work_items_data.get("work_items", {})
+        work_items_data["metadata"]["total_items"] = len(work_items)
+        work_items_data["metadata"]["completed"] = sum(
+            1 for item in work_items.values() if item["status"] == WorkItemStatus.COMPLETED.value
+        )
+        work_items_data["metadata"]["in_progress"] = sum(
+            1 for item in work_items.values() if item["status"] == WorkItemStatus.IN_PROGRESS.value
+        )
+        work_items_data["metadata"]["blocked"] = sum(
+            1 for item in work_items.values() if item["status"] == WorkItemStatus.BLOCKED.value
+        )
+        work_items_data["metadata"]["last_updated"] = datetime.now().isoformat()
+
+        # Save updated work items
+        with open(self.work_items_file, "w") as f:
+            json.dump(work_items_data, f, indent=2)
+
+        logger.info("Updated work item %s status to %s", work_item_id, status)
+        return True