solokit 0.1.1__py3-none-any.whl

solokit/work_items/__init__.py

@@ -0,0 +1 @@
+"""Work item management including specs, validation, and CRUD operations."""

solokit/work_items/creator.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""
+Work Item Creator - Interactive and non-interactive work item creation.
+
+Handles user prompts, ID generation, and spec file creation.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from solokit.core.error_handlers import log_errors
+from solokit.core.exceptions import (
+    ErrorCode,
+    ValidationError,
+    WorkItemAlreadyExistsError,
+)
+from solokit.core.logging_config import get_logger
+from solokit.core.types import WorkItemStatus, WorkItemType
+
+if TYPE_CHECKING:
+    from .repository import WorkItemRepository
+from solokit.core.output import get_output
+
+logger = get_logger(__name__)
+output = get_output()
+
+
+class WorkItemCreator:
+    """Handles work item creation with interactive and non-interactive modes"""
+
+    WORK_ITEM_TYPES = WorkItemType.values()
+    PRIORITIES = ["critical", "high", "medium", "low"]
+
+    def __init__(self, repository: WorkItemRepository):
+        """Initialize creator with repository
+
+        Args:
+            repository: WorkItemRepository instance for data access
+        """
+        self.repository = repository
+        self.project_root = repository.session_dir.parent
+        self.specs_dir = repository.session_dir / "specs"
+        self.templates_dir = Path(__file__).parent.parent / "templates"
+
+    @log_errors()
+    def create_from_args(
+        self, work_type: str, title: str, priority: str = "high", dependencies: str = ""
+    ) -> str:
+        """Create work item from command-line arguments (non-interactive)
+
+        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
+        """
+        logger.info("Creating work item from args: type=%s, title=%s", work_type, title)
+
+        # Validate work type
+        if work_type not in self.WORK_ITEM_TYPES:
+            logger.error("Invalid work item type: %s", work_type)
+            raise ValidationError(
+                message=f"Invalid work item type '{work_type}'",
+                code=ErrorCode.INVALID_WORK_ITEM_TYPE,
+                context={"work_type": work_type, "valid_types": self.WORK_ITEM_TYPES},
+                remediation=f"Valid types: {', '.join(self.WORK_ITEM_TYPES)}",
+            )
+
+        # Validate priority
+        if priority not in self.PRIORITIES:
+            logger.warning("Invalid priority '%s', using 'high'", priority)
+            logger.warning("Invalid priority '%s', using 'high'", priority)
+            priority = "high"
+
+        # Parse dependencies
+        dep_list = []
+        if dependencies:
+            dep_list = [d.strip() for d in dependencies.split(",") if d.strip()]
+            logger.debug("Parsed dependencies: %s", dep_list)
+            # Validate dependencies exist
+            for dep_id in dep_list:
+                if not self.repository.work_item_exists(dep_id):
+                    logger.warning("Dependency '%s' does not exist", dep_id)
+                    logger.warning("Warning: Dependency '%s' does not exist", dep_id)
+
+        # Generate ID
+        work_id = self._generate_id(work_type, title)
+        logger.debug("Generated work item ID: %s", work_id)
+
+        # Check for duplicates
+        if self.repository.work_item_exists(work_id):
+            logger.error("Work item %s already exists", work_id)
+            raise WorkItemAlreadyExistsError(work_id)
+
+        # Create specification file
+        spec_file = self._create_spec_file(work_id, work_type, title)
+        if not spec_file:
+            logger.warning("Could not create specification file for %s", work_id)
+            logger.warning("Warning: Could not create specification file")
+
+        # Add to work_items.json
+        self.repository.add_work_item(work_id, work_type, title, priority, dep_list, spec_file)
+        logger.info("Work item created: %s (type=%s, priority=%s)", work_id, work_type, priority)
+
+        # Confirm
+        self._print_creation_confirmation(work_id, work_type, priority, dep_list, spec_file)
+
+        return work_id
+
+    def _generate_id(self, work_type: str, title: str) -> str:
+        """Generate work item ID from type and title
+
+        Args:
+            work_type: Type of work item
+            title: Work item title
+
+        Returns:
+            str: Generated work item ID
+        """
+        # Clean title: lowercase, alphanumeric + underscore only
+        clean_title = re.sub(r"[^a-z0-9]+", "_", title.lower())
+        clean_title = clean_title.strip("_")
+
+        # Truncate if too long
+        if len(clean_title) > 30:
+            clean_title = clean_title[:30]
+
+        return f"{work_type}_{clean_title}"
+
+    def _create_spec_file(self, work_id: str, work_type: str, title: str) -> str:
+        """Create specification file from template
+
+        Args:
+            work_id: Work item ID
+            work_type: Type of work item
+            title: Work item title
+
+        Returns:
+            str: Relative path to the created spec file, or empty string if failed
+        """
+        # Ensure specs directory exists
+        self.specs_dir.mkdir(parents=True, exist_ok=True)
+
+        # Load template
+        template_file = self.templates_dir / f"{work_type}_spec.md"
+        if not template_file.exists():
+            return ""
+
+        template_content = template_file.read_text()
+
+        # Replace title placeholder
+        if work_type == "feature":
+            spec_content = template_content.replace("[Feature Name]", title)
+        elif work_type == "bug":
+            spec_content = template_content.replace("[Bug Title]", title)
+        elif work_type == "refactor":
+            spec_content = template_content.replace("[Refactor Title]", title)
+        elif work_type == "security":
+            spec_content = template_content.replace("[Name]", title)
+        elif work_type == "integration_test":
+            spec_content = template_content.replace("[Name]", title)
+        elif work_type == "deployment":
+            spec_content = template_content.replace("[Environment]", title)
+        else:
+            spec_content = template_content
+
+        # Save spec file
+        spec_path = self.specs_dir / f"{work_id}.md"
+        spec_path.write_text(spec_content)
+
+        # Return relative path from project root
+        return f".session/specs/{work_id}.md"
+
+    def _print_creation_confirmation(
+        self,
+        work_id: str,
+        work_type: str,
+        priority: str,
+        dependencies: list[str],
+        spec_file: str,
+    ) -> None:
+        """Print creation confirmation message
+
+        Args:
+            work_id: Created work item ID
+            work_type: Work item type
+            priority: Priority level
+            dependencies: List of dependency IDs
+            spec_file: Path to spec file
+        """
+        output.info(f"\n{'=' * 50}")
+        output.info("Work item created successfully!")
+        output.info("=" * 50)
+        output.info(f"\nID: {work_id}")
+        output.info(f"Type: {work_type}")
+        output.info(f"Priority: {priority}")
+        output.info(f"Status: {WorkItemStatus.NOT_STARTED.value}")
+        if dependencies:
+            output.info(f"Dependencies: {', '.join(dependencies)}")
+
+        if spec_file:
+            output.info(f"\nSpecification saved to: {spec_file}")
+
+        output.info("\nNext steps:")
+        output.info(f"1. Edit specification: {spec_file}")
+        output.info("2. Start working: /start")
+        output.info("")

solokit/work_items/delete.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""
+Work Item Deletion - Safe deletion of work items.
+
+Handles deletion of work items with dependency checking and interactive confirmation.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from solokit.core.error_handlers import log_errors
+from solokit.core.exceptions import (
+    FileNotFoundError as SolokitFileNotFoundError,
+)
+from solokit.core.exceptions import (
+    FileOperationError,
+    ValidationError,
+    WorkItemNotFoundError,
+)
+from solokit.core.file_ops import load_json, save_json
+from solokit.core.logging_config import get_logger
+from solokit.core.output import get_output
+from solokit.core.types import WorkItemStatus
+
+logger = get_logger(__name__)
+output = get_output()
+
+
+def find_dependents(work_items: dict, work_item_id: str) -> list[str]:
+    """
+    Find work items that depend on the given work item.
+
+    Args:
+        work_items: Dictionary of all work items
+        work_item_id: ID to find dependents for
+
+    Returns:
+        List of work item IDs that depend on this item
+    """
+    dependents = []
+    for wid, item in work_items.items():
+        deps = item.get("dependencies", [])
+        if work_item_id in deps:
+            dependents.append(wid)
+    return dependents
+
+
+@log_errors()
+def delete_work_item(
+    work_item_id: str, delete_spec: Optional[bool] = None, project_root: Optional[Path] = None
+) -> bool:
+    """
+    Delete a work item from the system.
+
+    Args:
+        work_item_id: ID of work item to delete
+        delete_spec: Whether to also delete the spec file (None for interactive prompt)
+        project_root: Project root path (defaults to current directory)
+
+    Returns:
+        True if deletion successful, False if user cancels
+
+    Raises:
+        SolokitFileNotFoundError: If work_items.json doesn't exist
+        WorkItemNotFoundError: If work item ID doesn't exist
+        FileOperationError: If unable to load or save work items file
+        ValidationError: If running in non-interactive mode without flags
+    """
+    # Setup paths
+    if project_root is None:
+        project_root = Path.cwd()
+
+    session_dir = project_root / ".session"
+    work_items_file = session_dir / "tracking" / "work_items.json"
+
+    # Check if work items file exists
+    if not work_items_file.exists():
+        logger.error("Work items file not found")
+        raise SolokitFileNotFoundError(file_path=str(work_items_file), file_type="work items")
+
+    # Load work items
+    try:
+        work_items_data = load_json(work_items_file)
+    except (OSError, ValueError) as e:
+        logger.error("Failed to load work items: %s", e)
+        raise FileOperationError(
+            operation="read", file_path=str(work_items_file), details=str(e), cause=e
+        ) from e
+
+    work_items = work_items_data.get("work_items", {})
+
+    # Validate work item exists
+    if work_item_id not in work_items:
+        logger.error("Work item '%s' not found", work_item_id)
+        raise WorkItemNotFoundError(work_item_id)
+
+    item = work_items[work_item_id]
+
+    # Find dependents
+    dependents = find_dependents(work_items, work_item_id)
+
+    # Show work item details
+    output.warning(f"\nThis will permanently delete work item '{work_item_id}'")
+    output.info("\nWork item details:")
+    output.info(f"  Title: {item.get('title', 'N/A')}")
+    output.info(f"  Type: {item.get('type', 'N/A')}")
+    output.info(f"  Status: {item.get('status', 'N/A')}")
+
+    dependencies = item.get("dependencies", [])
+    if dependencies:
+        output.info(f"  Dependencies: {', '.join(dependencies)}")
+    else:
+        output.info("  Dependencies: none")
+
+    if dependents:
+        output.info(
+            f"  Dependents: {', '.join(dependents)} ({len(dependents)} item(s) depend on this)"
+        )
+    else:
+        output.info("  Dependents: none")
+
+    # Require explicit flag (no interactive mode)
+    if delete_spec is None:
+        logger.error("Must specify --keep-spec or --delete-spec flag")
+        raise ValidationError(
+            message="Must specify either --keep-spec or --delete-spec flag",
+            remediation=(
+                "Use command-line flags:\n"
+                "  sk work-delete <work_item_id> --keep-spec   (delete work item only)\n"
+                "  sk work-delete <work_item_id> --delete-spec (delete work item and spec)"
+            ),
+        )
+
+    # Show what will be done
+    if delete_spec:
+        output.info("\n→ Will delete work item and spec file")
+    else:
+        output.info("\n→ Will delete work item only (keeping spec file)")
+
+    # Perform deletion
+    logger.info("Deleting work item '%s'", work_item_id)
+    del work_items[work_item_id]
+
+    # Update metadata
+    work_items_data["work_items"] = work_items
+    if "metadata" not in work_items_data:
+        work_items_data["metadata"] = {}
+
+    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
+    )
+
+    # Save work items
+    try:
+        save_json(work_items_file, work_items_data)
+        logger.info("Successfully updated work_items.json")
+        output.info(f"✓ Deleted work item '{work_item_id}'")
+    except OSError as e:
+        logger.error("Failed to save work items: %s", e)
+        raise FileOperationError(
+            operation="write", file_path=str(work_items_file), details=str(e), cause=e
+        ) from e
+
+    # Delete spec file if requested
+    if delete_spec:
+        spec_file_path = item.get("spec_file", f".session/specs/{work_item_id}.md")
+        spec_path = project_root / spec_file_path
+
+        if spec_path.exists():
+            try:
+                spec_path.unlink()
+                logger.info("Deleted spec file: %s", spec_file_path)
+                output.info(f"✓ Deleted spec file '{spec_file_path}'")
+            except (OSError, PermissionError) as e:
+                logger.warning("Failed to delete spec file: %s", e)
+                output.warning(f"Could not delete spec file: {e}")
+        else:
+            logger.debug("Spec file not found: %s", spec_file_path)
+            output.info(f"Note: Spec file '{spec_file_path}' not found")
+
+    # Warn about dependents
+    if dependents:
+        output.warning("\nThe following work items depend on this item:")
+        for dep in dependents:
+            output.info(f"    - {dep}")
+        output.info("  Update their dependencies manually if needed.")
+
+    output.info("\nDeletion successful.")
+    logger.info("Work item deletion completed successfully")
+    return True
+
+
+def main() -> int:
+    """CLI entry point for work item deletion."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Delete a work item")
+    parser.add_argument("work_item_id", help="ID of work item to delete")
+    parser.add_argument(
+        "--keep-spec",
+        action="store_true",
+        help="Keep the spec file (delete work item only)",
+    )
+    parser.add_argument(
+        "--delete-spec",
+        action="store_true",
+        help="Delete both work item and spec file",
+    )
+
+    args = parser.parse_args()
+
+    # Determine delete_spec value
+    delete_spec_value = None
+    if args.keep_spec and args.delete_spec:
+        raise ValidationError(
+            message="Cannot specify both --keep-spec and --delete-spec",
+            remediation="Choose only one option: --keep-spec OR --delete-spec",
+        )
+    elif args.keep_spec:
+        delete_spec_value = False
+    elif args.delete_spec:
+        delete_spec_value = True
+
+    # Perform deletion
+    try:
+        success = delete_work_item(args.work_item_id, delete_spec=delete_spec_value)
+        return 0 if success else 1
+    except WorkItemNotFoundError as e:
+        output.info(f"❌ Error: {e.message}")
+        if e.remediation:
+            output.info(f"\n{e.remediation}")
+        # Show available work items
+        try:
+            from pathlib import Path
+
+            work_items_file = Path.cwd() / ".session" / "tracking" / "work_items.json"
+            if work_items_file.exists():
+                work_items_data = load_json(work_items_file)
+                work_items = work_items_data.get("work_items", {})
+                if work_items:
+                    output.info("\nAvailable work items:")
+                    for wid in list(work_items.keys())[:5]:
+                        output.info(f"  - {wid}")
+                    if len(work_items) > 5:
+                        output.info(f"  ... and {len(work_items) - 5} more")
+        except Exception:  # noqa: BLE001 - This is optional enhancement, don't fail on it
+            pass
+        return e.exit_code
+    except (SolokitFileNotFoundError, FileOperationError, ValidationError) as e:
+        output.info(f"❌ Error: {e.message}")
+        if e.remediation:
+            output.info(f"\n{e.remediation}")
+        return e.exit_code
+
+
+if __name__ == "__main__":
+    exit(main())

solokit/work_items/get_dependencies.py

@@ -0,0 +1,185 @@
+"""Fast dependency information retrieval for Claude Code integration.
+
+This module provides optimized dependency lookups without reading full spec files.
+Used by /work-new and /work-delete commands to fetch available dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def get_available_dependencies(
+    exclude_statuses: list[str] | None = None,
+    title_filter: str | None = None,
+    max_results: int = 3,
+) -> list[dict[str, Any]]:
+    """Get available work items that can be used as dependencies.
+
+    Args:
+        exclude_statuses: List of statuses to exclude (default: ["completed"])
+        title_filter: Optional title to use for smart filtering/relevance
+        max_results: Maximum number of results to return (default: 3)
+
+    Returns:
+        List of dependency info dicts with keys: id, type, title, status
+
+    Raises:
+        FileNotFoundError: If work_items.json doesn't exist
+        json.JSONDecodeError: If work_items.json is invalid
+    """
+    if exclude_statuses is None:
+        exclude_statuses = ["completed"]
+
+    # 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 []
+
+    # Filter available dependencies
+    available = []
+    for work_id, item in work_items.items():
+        status = item.get("status", "unknown")
+        if status not in exclude_statuses:
+            available.append(
+                {
+                    "id": work_id,
+                    "type": item.get("type", "unknown"),
+                    "title": item.get("title", "Untitled"),
+                    "status": status,
+                }
+            )
+
+    # Apply smart filtering if title provided
+    if title_filter and available:
+        available = _filter_by_relevance(available, title_filter)
+
+    # Limit results
+    return available[:max_results]
+
+
+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 _filter_by_relevance(items: list[dict], title: str) -> list[dict]:
+    """Filter and sort items by relevance to the given title.
+
+    Simple keyword-based relevance scoring:
+    - Exact word matches in title get highest score
+    - Partial matches get medium score
+    - Items with same type get bonus points
+
+    Args:
+        items: List of work item dicts
+        title: Title to compare against
+
+    Returns:
+        Sorted list (most relevant first)
+    """
+    title_lower = title.lower()
+    title_words = set(title_lower.split())
+
+    def relevance_score(item: dict) -> float:
+        item_title_lower = item["title"].lower()
+        item_words = set(item_title_lower.split())
+
+        # Exact word matches (high weight)
+        word_matches = len(title_words & item_words)
+
+        # Partial matches (medium weight)
+        partial_matches = sum(1 for tw in title_words for iw in item_words if tw in iw or iw in tw)
+
+        # Calculate score
+        score = (word_matches * 3.0) + (partial_matches * 1.5)
+
+        return score
+
+    # Score and sort
+    scored = [(item, relevance_score(item)) for item in items]
+    scored.sort(key=lambda x: x[1], reverse=True)
+
+    # Return only items with non-zero scores, or all if none match
+    relevant = [item for item, score in scored if score > 0]
+    return relevant if relevant else items
+
+
+def main() -> None:
+    """CLI entry point for get_dependencies script.
+
+    Usage:
+        python -m solokit.work_items.get_dependencies
+        python -m solokit.work_items.get_dependencies --title "My new feature"
+        python -m solokit.work_items.get_dependencies --title "Bug fix" --max 5
+        python -m solokit.work_items.get_dependencies --exclude-status not_started,in_progress
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Get available dependencies for work items")
+    parser.add_argument("--title", help="Optional title for smart filtering by relevance")
+    parser.add_argument("--max", type=int, default=3, help="Maximum number of results (default: 3)")
+    parser.add_argument(
+        "--exclude-status", help="Comma-separated list of statuses to exclude (default: completed)"
+    )
+
+    args = parser.parse_args()
+
+    # Parse exclude statuses
+    exclude = None
+    if args.exclude_status:
+        exclude = [s.strip() for s in args.exclude_status.split(",")]
+
+    # Get dependencies
+    dependencies = get_available_dependencies(
+        exclude_statuses=exclude,
+        title_filter=args.title,
+        max_results=args.max,
+    )
+
+    # Output results
+    if not dependencies:
+        print("No available dependencies found")
+        sys.exit(1)
+
+    print(f"Found {len(dependencies)} available dependencies:")
+    print()
+    for dep in dependencies:
+        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()