solokit 0.1.1__py3-none-any.whl

solokit/work_items/get_dependents.py

@@ -0,0 +1,113 @@
+"""Fast dependent lookup for Claude Code integration.
+
+This module provides optimized lookup of work items that depend on a given work item.
+Used by /work-delete command to check if deleting a work item will affect others.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def get_dependents(work_item_id: str) -> list[dict[str, Any]]:
+    """Get list of work items that depend on the given work item.
+
+    Args:
+        work_item_id: ID of the work item to check for dependents
+
+    Returns:
+        List of dependent work items with keys: id, type, title, status
+
+    Raises:
+        FileNotFoundError: If work_items.json doesn't exist
+        json.JSONDecodeError: If work_items.json is invalid
+    """
+    # Find .session directory
+    session_dir = _find_session_dir()
+    if not session_dir:
+        print("Error: Not in an Solokit project (no .session directory found)", file=sys.stderr)
+        return []
+
+    # Load work items
+    work_items_file = session_dir / "tracking" / "work_items.json"
+    if not work_items_file.exists():
+        print(f"Error: Work items file not found: {work_items_file}", file=sys.stderr)
+        return []
+
+    try:
+        with open(work_items_file) as f:
+            data = json.load(f)
+    except json.JSONDecodeError as e:
+        print(f"Error: Invalid JSON in {work_items_file}: {e}", file=sys.stderr)
+        return []
+
+    # Extract work_items from the data structure
+    work_items = data.get("work_items", {})
+    if not work_items:
+        print("No work items found", file=sys.stderr)
+        return []
+
+    # Find dependents (work items that have this work_item_id in their dependencies)
+    dependents = []
+    for item_id, item in work_items.items():
+        dependencies = item.get("dependencies", [])
+        if work_item_id in dependencies:
+            dependents.append(
+                {
+                    "id": item_id,
+                    "type": item.get("type", "unknown"),
+                    "title": item.get("title", "Untitled"),
+                    "status": item.get("status", "unknown"),
+                }
+            )
+
+    return dependents
+
+
+def _find_session_dir() -> Path | None:
+    """Find the .session directory by walking up from current directory."""
+    current = Path.cwd()
+    while current != current.parent:
+        session_dir = current / ".session"
+        if session_dir.is_dir():
+            return session_dir
+        current = current.parent
+    return None
+
+
+def main() -> None:
+    """CLI entry point for get_dependents script.
+
+    Usage:
+        python -m solokit.work_items.get_dependents <work_item_id>
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Get work items that depend on a given work item")
+    parser.add_argument("work_item_id", help="ID of the work item to check for dependents")
+
+    args = parser.parse_args()
+
+    # Get dependents
+    dependents = get_dependents(args.work_item_id)
+
+    # Output results
+    if not dependents:
+        print(f"No work items depend on '{args.work_item_id}'")
+        sys.exit(0)
+
+    print(f"Found {len(dependents)} work item(s) that depend on '{args.work_item_id}':")
+    print()
+    for dep in dependents:
+        print(f"ID: {dep['id']}")
+        print(f"Type: {dep['type']}")
+        print(f"Title: {dep['title']}")
+        print(f"Status: {dep['status']}")
+        print()
+
+
+if __name__ == "__main__":
+    main()

solokit/work_items/get_metadata.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+Get work item metadata without loading full spec.
+
+Lightweight utility to fetch just the metadata fields for a work item,
+avoiding the overhead of loading and displaying full specifications.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+def get_work_item_metadata(
+    work_item_id: str, include_dependency_details: bool = False
+) -> dict | None:
+    """Get work item metadata without loading spec file.
+
+    Args:
+        work_item_id: ID of the work item
+        include_dependency_details: If True, include full details (type, title) for each dependency
+
+    Returns:
+        dict: Work item metadata (id, type, title, status, priority, dependencies, milestone)
+              If include_dependency_details=True, also includes 'dependency_details' list
+        None: If work item doesn't exist
+    """
+    # Find work_items.json
+    session_dir = Path.cwd() / ".session"
+    work_items_file = session_dir / "tracking" / "work_items.json"
+
+    if not work_items_file.exists():
+        return None
+
+    # Load work items
+    with open(work_items_file) as f:
+        data = json.load(f)
+
+    work_items = data.get("work_items", {})
+
+    if work_item_id not in work_items:
+        return None
+
+    item = work_items[work_item_id]
+
+    # Build metadata
+    metadata = {
+        "id": item["id"],
+        "type": item["type"],
+        "title": item["title"],
+        "status": item["status"],
+        "priority": item["priority"],
+        "dependencies": item.get("dependencies", []),
+        "milestone": item.get("milestone", ""),
+    }
+
+    # Optionally include dependency details (fetch all in one pass)
+    if include_dependency_details and metadata["dependencies"]:
+        dep_details = []
+        for dep_id in metadata["dependencies"]:
+            if dep_id in work_items:
+                dep_item = work_items[dep_id]
+                dep_details.append(
+                    {
+                        "id": dep_id,
+                        "type": dep_item["type"],
+                        "title": dep_item["title"],
+                        "status": dep_item.get("status", "unknown"),
+                    }
+                )
+        metadata["dependency_details"] = dep_details
+
+    return metadata
+
+
+def main() -> int:
+    """CLI entry point."""
+    if len(sys.argv) < 2:
+        print(
+            "Usage: python -m solokit.work_items.get_metadata <work_item_id> [--with-deps]",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    work_item_id = sys.argv[1]
+    include_deps = "--with-deps" in sys.argv
+
+    metadata = get_work_item_metadata(work_item_id, include_dependency_details=include_deps)
+
+    if metadata is None:
+        print(f"Error: Work item '{work_item_id}' not found", file=sys.stderr)
+        sys.exit(1)
+
+    # Print in a clean, parseable format
+    print(f"ID: {metadata['id']}")
+    print(f"Type: {metadata['type']}")
+    print(f"Title: {metadata['title']}")
+    print(f"Status: {metadata['status']}")
+    print(f"Priority: {metadata['priority']}")
+    print(f"Milestone: {metadata['milestone'] or '(none)'}")
+
+    if metadata["dependencies"]:
+        if "dependency_details" in metadata:
+            # Print with full details
+            deps_str = []
+            for dep in metadata["dependency_details"]:
+                deps_str.append(f"{dep['id']} ([{dep['type']}] {dep['title']} - {dep['status']})")
+            print("Dependencies:\n  " + "\n  ".join(deps_str))
+        else:
+            # Print just IDs
+            print(f"Dependencies: {', '.join(metadata['dependencies'])}")
+    else:
+        print("Dependencies: (none)")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

solokit/work_items/get_next_recommendations.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""
+Get next recommended work items for interactive selection.
+
+This script returns the top 4 ready-to-start work items based on:
+- Dependencies are satisfied (not blocked)
+- Priority (critical > high > medium > low)
+- Status is not_started
+
+Output format (one per line):
+work_item_id | type | title | priority
+
+Usage:
+    python -m solokit.work_items.get_next_recommendations [--limit N]
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def get_ready_work_items(limit: int = 4) -> list[dict[str, Any]]:
+    """Get list of ready-to-start work items sorted by priority.
+
+    Args:
+        limit: Maximum number of items to return (default 4)
+
+    Returns:
+        list: Ready work items with id, type, title, priority
+    """
+    # Find work_items.json
+    work_items_file = Path(".session/tracking/work_items.json")
+    if not work_items_file.exists():
+        print("Error: .session/tracking/work_items.json not found", file=sys.stderr)
+        return []
+
+    # Load work items
+    try:
+        with open(work_items_file) as f:
+            data = json.load(f)
+    except json.JSONDecodeError as e:
+        print(f"Error: Invalid JSON in {work_items_file}: {e}", file=sys.stderr)
+        return []
+
+    # Extract work_items from data structure
+    work_items = data.get("work_items", {})
+    if not work_items:
+        print("No work items found", file=sys.stderr)
+        return []
+
+    # Filter to not_started items
+    not_started = {
+        wid: item for wid, item in work_items.items() if item.get("status") == "not_started"
+    }
+
+    if not not_started:
+        print("No work items available to start", file=sys.stderr)
+        return []
+
+    # Check dependencies and filter to ready items
+    ready_items = []
+
+    for work_id, item in not_started.items():
+        dependencies = item.get("dependencies", [])
+
+        # Check if all dependencies are completed
+        is_ready = True
+        if dependencies:
+            for dep_id in dependencies:
+                dep_item = work_items.get(dep_id)
+                if not dep_item or dep_item.get("status") != "completed":
+                    is_ready = False
+                    break
+
+        if is_ready:
+            ready_items.append(
+                {
+                    "id": work_id,
+                    "type": item.get("type", "unknown"),
+                    "title": item.get("title", "Untitled"),
+                    "priority": item.get("priority", "medium"),
+                }
+            )
+
+    if not ready_items:
+        print("No work items ready to start. All have unmet dependencies.", file=sys.stderr)
+        return []
+
+    # Sort by priority (critical > high > medium > low)
+    priority_order = {
+        "critical": 0,
+        "high": 1,
+        "medium": 2,
+        "low": 3,
+    }
+    ready_items.sort(key=lambda x: priority_order.get(x["priority"], 99))
+
+    # Return top N items
+    return ready_items[:limit]
+
+
+def main() -> int:
+    """Main entry point for script."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Get next recommended work items for interactive selection"
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=4,
+        help="Maximum number of recommendations to return (default: 4)",
+    )
+    args = parser.parse_args()
+
+    ready_items = get_ready_work_items(limit=args.limit)
+
+    if not ready_items:
+        sys.exit(1)
+
+    # Output format: work_item_id | type | title | priority
+    for item in ready_items:
+        print(f"{item['id']} | {item['type']} | {item['title']} | {item['priority']}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

solokit/work_items/manager.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""
+Work Item Manager - Main orchestrator for work item operations.
+
+Delegates to specialized modules for different concerns:
+- creator: Work item creation and prompts
+- repository: Data access and persistence
+- validator: Validation logic
+- query: Listing, filtering, and display
+- updater: Update operations
+- scheduler: Work queue and next item selection
+- milestones: Milestone management
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from solokit.core.constants import get_session_dir, get_specs_dir
+from solokit.core.types import Priority, WorkItemType
+
+from .creator import WorkItemCreator
+from .milestones import MilestoneManager
+from .query import WorkItemQuery
+from .repository import WorkItemRepository
+from .scheduler import WorkItemScheduler
+from .updater import WorkItemUpdater
+from .validator import WorkItemValidator
+
+
+class WorkItemManager:
+    """Main orchestrator for work item operations"""
+
+    WORK_ITEM_TYPES = WorkItemType.values()
+    PRIORITIES = Priority.values()
+
+    def __init__(self, project_root: Path | None = None):
+        """Initialize manager with dependency injection
+
+        Args:
+            project_root: Optional project root path (defaults to current directory)
+        """
+        self.project_root = project_root or Path.cwd()
+        self.session_dir = get_session_dir(self.project_root)
+
+        # Initialize components
+        self.repository = WorkItemRepository(self.session_dir)
+        self.creator = WorkItemCreator(self.repository)
+        self.validator = WorkItemValidator()
+        self.query = WorkItemQuery(self.repository)
+        self.updater = WorkItemUpdater(self.repository, self.validator)
+        self.scheduler = WorkItemScheduler(self.repository)
+        self.milestones = MilestoneManager(self.repository)
+
+        # Legacy compatibility - maintain these paths for backward compatibility
+        self.work_items_file = self.repository.work_items_file
+        self.specs_dir = get_specs_dir(self.project_root)
+        self.templates_dir = Path(__file__).parent.parent / "templates"
+
+    # Delegate creation methods
+    def create_work_item_from_args(
+        self, work_type: str, title: str, priority: str = "high", dependencies: str = ""
+    ) -> str:
+        """Create work item from command-line arguments
+
+        Args:
+            work_type: Type of work item (feature, bug, refactor, etc.)
+            title: Title of the work item
+            priority: Priority level (critical, high, medium, low)
+            dependencies: Comma-separated dependency IDs
+
+        Returns:
+            str: The created work item ID
+
+        Raises:
+            ValidationError: If work type is invalid
+            WorkItemAlreadyExistsError: If work item with generated ID already exists
+            FileOperationError: If spec file creation or tracking update fails
+        """
+        return self.creator.create_from_args(work_type, title, priority, dependencies)
+
+    # Delegate query methods
+    def list_work_items(
+        self,
+        status_filter: str | None = None,
+        type_filter: str | None = None,
+        milestone_filter: str | None = None,
+    ) -> dict:
+        """List work items with optional filters
+
+        Args:
+            status_filter: Optional status filter
+            type_filter: Optional type filter
+            milestone_filter: Optional milestone filter
+
+        Returns:
+            dict: Dictionary with 'items' list and 'count'
+        """
+        return self.query.list_items(status_filter, type_filter, milestone_filter)
+
+    def show_work_item(self, work_id: str) -> dict[str, Any]:
+        """Show detailed information about a work item
+
+        Args:
+            work_id: ID of the work item to display
+
+        Returns:
+            dict: The work item data
+
+        Raises:
+            FileOperationError: If work_items.json doesn't exist
+            WorkItemNotFoundError: If work item doesn't exist
+        """
+        return self.query.show_item(work_id)
+
+    # Delegate update methods
+    def update_work_item(self, work_id: str, **updates: Any) -> None:
+        """Update a work item
+
+        Args:
+            work_id: ID of the work item to update
+            **updates: Field updates (status, priority, milestone, add_dependency, remove_dependency)
+
+        Raises:
+            FileOperationError: If work_items.json doesn't exist
+            WorkItemNotFoundError: If work item doesn't exist
+            ValidationError: If invalid status or priority provided
+        """
+        return self.updater.update(work_id, **updates)
+
+    # Delegate scheduler methods
+    def get_next_work_item(self) -> dict[str, Any] | None:
+        """Get next recommended work item based on dependencies and priority
+
+        Returns:
+            dict: Next work item to start, or None if none available
+        """
+        return self.scheduler.get_next()
+
+    # Delegate validation methods
+    def validate_integration_test(self, work_item: dict) -> None:
+        """Validate integration test work item
+
+        Args:
+            work_item: Work item dictionary to validate
+
+        Raises:
+            FileOperationError: If spec file not found
+            ValidationError: If spec validation fails (with validation errors in context)
+        """
+        return self.validator.validate_integration_test(work_item)
+
+    def validate_deployment(self, work_item: dict) -> None:
+        """Validate deployment work item
+
+        Args:
+            work_item: Work item dictionary to validate
+
+        Raises:
+            FileOperationError: If spec file not found
+            ValidationError: If spec validation fails (with validation errors in context)
+        """
+        return self.validator.validate_deployment(work_item)
+
+    # Delegate milestone methods
+    def create_milestone(
+        self, name: str, title: str, description: str, target_date: str | None = None
+    ) -> None:
+        """Create a new milestone
+
+        Args:
+            name: Milestone name (unique identifier)
+            title: Milestone title
+            description: Milestone description
+            target_date: Optional target completion date
+
+        Raises:
+            ValidationError: If milestone with this name already exists
+            FileOperationError: If saving milestone fails
+        """
+        return self.milestones.create(name, title, description, target_date)
+
+    def get_milestone_progress(self, milestone_name: str) -> dict:
+        """Get milestone progress
+
+        Args:
+            milestone_name: Name of the milestone
+
+        Returns:
+            dict: Progress statistics including total, completed, in_progress, not_started, percent
+        """
+        return self.milestones.get_progress(milestone_name)
+
+    def list_milestones(self) -> None:
+        """List all milestones with progress"""
+        return self.milestones.list_all()
+
+
+def main() -> int:
+    """CLI entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Work Item Manager")
+    parser.add_argument(
+        "--type",
+        help="Work item type (feature, bug, refactor, security, integration_test, deployment)",
+    )
+    parser.add_argument("--title", help="Work item title")
+    parser.add_argument("--priority", default="high", help="Priority (critical, high, medium, low)")
+    parser.add_argument("--dependencies", default="", help="Comma-separated dependency IDs")
+
+    args = parser.parse_args()
+
+    manager = WorkItemManager()
+
+    # Require type and title arguments (no interactive mode)
+    if not args.type or not args.title:
+        parser.error("Both --type and --title are required")
+
+    work_id = manager.create_work_item_from_args(
+        work_type=args.type,
+        title=args.title,
+        priority=args.priority,
+        dependencies=args.dependencies,
+    )
+
+    if work_id:
+        return 0
+    else:
+        return 1
+
+
+if __name__ == "__main__":
+    exit(main())