solokit 0.1.1__py3-none-any.whl

solokit/__init__.py

@@ -0,0 +1,10 @@
+"""Session-Driven Development (Solokit) - AI-Augmented Development Workflow System.
+
+Solokit is a structured workflow system for AI-augmented software development that organizes
+work into discrete sessions, each focused on completing a single work item with
+comprehensive context, quality gates, and learning capture.
+"""
+
+from solokit.__version__ import __version__
+
+__all__ = ["__version__"]

solokit/__version__.py

@@ -0,0 +1,3 @@
+"""Version information for Solokit package."""
+
+__version__ = "0.1.1"

solokit/cli.py

@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+"""
+Solokit CLI Entry Point
+
+Universal interface for all Session-Driven Development commands.
+
+Usage:
+    solokit <command> [args...]
+
+Examples:
+    sk work-list
+    sk work-list --status not_started
+    sk work-show feature_user_auth
+    sk start
+    sk learn-search "authentication"
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from solokit.core.error_formatter import ErrorFormatter
+
+# Import error handling infrastructure
+from solokit.core.exceptions import (
+    ErrorCode,
+    SolokitError,
+    SystemError,
+)
+
+# Import logging configuration
+from solokit.core.logging_config import get_logger, setup_logging
+from solokit.core.output import get_output
+
+logger = get_logger(__name__)
+output = get_output()
+
+# Command routing table
+# Format: 'command-name': (module_path, class_name, function_name, needs_argparse)
+# - module_path: Python import path
+# - class_name: Class to instantiate (None for standalone functions)
+# - function_name: Method or function to call
+# - needs_argparse: True if script has its own argparse handling
+COMMANDS = {
+    # Work Item Management (WorkItemManager class)
+    "work-list": (
+        "solokit.work_items.manager",
+        "WorkItemManager",
+        "list_work_items",
+        False,
+    ),
+    "work-next": (
+        "solokit.work_items.manager",
+        "WorkItemManager",
+        "get_next_work_item",
+        False,
+    ),
+    "work-show": (
+        "solokit.work_items.manager",
+        "WorkItemManager",
+        "show_work_item",
+        False,
+    ),
+    "work-update": (
+        "solokit.work_items.manager",
+        "WorkItemManager",
+        "update_work_item",
+        False,
+    ),
+    "work-new": (
+        "solokit.work_items.manager",
+        "WorkItemManager",
+        "create_work_item_from_args",
+        False,
+    ),
+    "work-delete": ("solokit.work_items.delete", None, "main", True),
+    # Dependency Graph (uses argparse in main)
+    "work-graph": ("solokit.visualization.dependency_graph", None, "main", True),
+    # Session Management (standalone main functions)
+    "start": ("solokit.session.briefing", None, "main", True),
+    "end": ("solokit.session.complete", None, "main", True),
+    "status": ("solokit.session.status", None, "get_session_status", False),
+    "validate": ("solokit.session.validate", None, "main", True),
+    # Learning System (uses argparse in main)
+    "learn": ("solokit.learning.curator", None, "main", True),
+    "learn-show": ("solokit.learning.curator", None, "main", True),
+    "learn-search": ("solokit.learning.curator", None, "main", True),
+    "learn-curate": ("solokit.learning.curator", None, "main", True),
+    # Project Initialization
+    "init": ("solokit.project.init", None, "main", True),
+}
+
+
+def parse_work_list_args(args: list[str]) -> argparse.Namespace:
+    """Parse arguments for work-list command."""
+    parser = argparse.ArgumentParser(description="List work items")
+    parser.add_argument("--status", help="Filter by status")
+    parser.add_argument("--type", help="Filter by type")
+    parser.add_argument("--milestone", help="Filter by milestone")
+    return parser.parse_args(args)
+
+
+def parse_work_show_args(args: list[str]) -> argparse.Namespace:
+    """Parse arguments for work-show command."""
+    parser = argparse.ArgumentParser(description="Show work item details")
+    parser.add_argument("work_id", help="Work item ID")
+    return parser.parse_args(args)
+
+
+def parse_work_new_args(args: list[str]) -> argparse.Namespace:
+    """Parse arguments for work-new command."""
+    parser = argparse.ArgumentParser(description="Create a new work item")
+    parser.add_argument(
+        "--type",
+        "-t",
+        required=True,
+        help="Work item type (feature, bug, refactor, security, integration_test, deployment)",
+    )
+    parser.add_argument("--title", "-T", required=True, help="Work item title")
+    parser.add_argument(
+        "--priority",
+        "-p",
+        required=True,
+        help="Priority (critical, high, medium, low)",
+    )
+    parser.add_argument("--dependencies", "-d", default="", help="Comma-separated dependency IDs")
+    return parser.parse_args(args)
+
+
+def parse_work_update_args(args: list[str]) -> argparse.Namespace:
+    """Parse arguments for work-update command."""
+    parser = argparse.ArgumentParser(description="Update work item fields")
+    parser.add_argument("work_id", help="Work item ID")
+    parser.add_argument(
+        "--status", help="Update status (not_started/in_progress/blocked/completed)"
+    )
+    parser.add_argument("--priority", help="Update priority (critical/high/medium/low)")
+    parser.add_argument("--milestone", help="Update milestone")
+    parser.add_argument("--add-dependency", help="Add dependency by ID")
+    parser.add_argument("--remove-dependency", help="Remove dependency by ID")
+    return parser.parse_args(args)
+
+
+def route_command(command_name: str, args: list[str]) -> int:
+    """
+    Route command to appropriate script/function.
+
+    Args:
+        command_name: Name of the command (e.g., 'work-list')
+        args: List of command-line arguments
+
+    Returns:
+        Exit code (0 for success, non-zero for error)
+
+    Raises:
+        SystemError: If command is unknown or execution fails
+    """
+    if command_name not in COMMANDS:
+        available = ", ".join(sorted(COMMANDS.keys()))
+        raise SystemError(
+            message=f"Unknown command '{command_name}'",
+            code=ErrorCode.INVALID_COMMAND,
+            context={"command": command_name, "available_commands": list(COMMANDS.keys())},
+            remediation=f"Available commands: {available}",
+        )
+
+    module_path, class_name, function_name, needs_argparse = COMMANDS[command_name]
+
+    try:
+        # Import the module
+        module = __import__(module_path, fromlist=[class_name or function_name])
+
+        # Handle different command types
+        if needs_argparse:
+            # Scripts with argparse: set sys.argv and call main()
+            # The script's own argparse will handle arguments
+            if command_name in ["learn", "learn-show", "learn-search", "learn-curate"]:
+                # Learning commands need special handling for subcommands
+                if command_name == "learn":
+                    sys.argv = ["learning_curator.py", "add-learning"] + args
+                elif command_name == "learn-show":
+                    sys.argv = ["learning_curator.py", "show-learnings"] + args
+                elif command_name == "learn-search":
+                    sys.argv = ["learning_curator.py", "search"] + args
+                elif command_name == "learn-curate":
+                    sys.argv = ["learning_curator.py", "curate"] + args
+            else:
+                # Other argparse commands (work-graph, start, end, validate)
+                sys.argv = [command_name] + args
+
+            func = getattr(module, function_name)
+            result = func()
+            return int(result) if result is not None else 0
+
+        elif class_name:
+            # Class-based commands: instantiate class and call method
+            cls = getattr(module, class_name)
+            instance = cls()
+            method = getattr(instance, function_name)
+
+            # Special argument handling for specific commands
+            if command_name == "work-list":
+                parsed = parse_work_list_args(args)
+                result = method(
+                    status_filter=parsed.status,
+                    type_filter=parsed.type,
+                    milestone_filter=parsed.milestone,
+                )
+            elif command_name == "work-show":
+                parsed = parse_work_show_args(args)
+                result = method(parsed.work_id)
+            elif command_name == "work-next":
+                result = method()
+            elif command_name == "work-new":
+                # Parse arguments (all required)
+                parsed = parse_work_new_args(args)
+                result = method(
+                    work_type=parsed.type,
+                    title=parsed.title,
+                    priority=parsed.priority,
+                    dependencies=parsed.dependencies,
+                )
+            elif command_name == "work-update":
+                # Parse arguments
+                parsed = parse_work_update_args(args)
+
+                # Build kwargs from provided flags
+                kwargs = {}
+                if parsed.status:
+                    kwargs["status"] = parsed.status
+                if parsed.priority:
+                    kwargs["priority"] = parsed.priority
+                if parsed.milestone:
+                    kwargs["milestone"] = parsed.milestone
+                if parsed.add_dependency:
+                    kwargs["add_dependency"] = parsed.add_dependency
+                if parsed.remove_dependency:
+                    kwargs["remove_dependency"] = parsed.remove_dependency
+
+                result = method(parsed.work_id, **kwargs)
+            else:
+                result = method()
+
+            # Handle different return types
+            if result is None:
+                return 0
+            elif isinstance(result, bool):
+                return 0 if result else 1
+            elif isinstance(result, int):
+                return result
+            else:
+                return 0
+
+        else:
+            # Standalone function commands
+            func = getattr(module, function_name)
+            result = func()
+            return int(result) if result is not None else 0
+
+    except ModuleNotFoundError as e:
+        raise SystemError(
+            message=f"Could not import module '{module_path}'",
+            code=ErrorCode.MODULE_NOT_FOUND,
+            context={"module_path": module_path, "command": command_name},
+            remediation="Check that the command is properly installed",
+            cause=e,
+        ) from e
+    except AttributeError as e:
+        raise SystemError(
+            message=f"Could not find function '{function_name}' in module '{module_path}'",
+            code=ErrorCode.FUNCTION_NOT_FOUND,
+            context={"function": function_name, "module": module_path, "command": command_name},
+            remediation="This appears to be an internal error - please report it",
+            cause=e,
+        ) from e
+    except SolokitError:
+        # Re-raise SolokitError exceptions to be caught by main()
+        raise
+    except Exception as e:
+        # Wrap unexpected exceptions
+        raise SystemError(
+            message=f"Unexpected error executing command '{command_name}'",
+            code=ErrorCode.COMMAND_FAILED,
+            context={"command": command_name},
+            cause=e,
+        ) from e
+
+
+def main() -> int:
+    """
+    Main entry point for CLI with centralized error handling.
+
+    This function implements the standard error handling pattern:
+    - Parse arguments
+    - Route to command handlers
+    - Catch all exceptions in centralized handler
+    - Format errors using ErrorFormatter
+    - Return appropriate exit codes
+
+    Returns:
+        Exit code (0 for success, non-zero for errors)
+    """
+    try:
+        # Parse global flags first
+        parser = argparse.ArgumentParser(
+            description="Session-Driven Development CLI",
+            add_help=False,  # Don't show help yet, let commands handle it
+        )
+        parser.add_argument(
+            "--verbose",
+            "-v",
+            action="store_true",
+            help="Enable verbose (DEBUG) logging",
+        )
+        parser.add_argument(
+            "--log-file",
+            type=str,
+            help="Write logs to file",
+        )
+
+        # Parse known args (global flags) and leave rest for command routing
+        args, remaining = parser.parse_known_args()
+
+        # Setup logging based on global flags
+        log_level = "DEBUG" if args.verbose else "INFO"
+        log_file = Path(args.log_file) if args.log_file else None
+        setup_logging(level=log_level, log_file=log_file)
+
+        # Check if command is provided
+        if len(remaining) < 1:
+            output.error("Usage: solokit [--verbose] [--log-file FILE] <command> [args...]")
+            output.error("\nGlobal flags:")
+            output.error("  --verbose, -v        Enable verbose (DEBUG) logging")
+            output.error("  --log-file FILE      Write logs to file")
+            output.error("\nAvailable commands:")
+            output.error("  Work Items:")
+            output.error(
+                "    work-list, work-next, work-show, work-update, work-new, work-delete, work-graph"
+            )
+            output.error("  Sessions:")
+            output.error("    start, end, status, validate")
+            output.error("  Learnings:")
+            output.error("    learn, learn-show, learn-search, learn-curate")
+            output.error("  Initialization:")
+            output.error("    init")
+            return 1
+
+        command = remaining[0]
+        command_args = remaining[1:]
+
+        # Route command - will raise exceptions on error
+        exit_code = route_command(command, command_args)
+        return exit_code
+
+    except SolokitError as e:
+        # Structured Solokit errors with proper formatting
+        ErrorFormatter.print_error(e, verbose=args.verbose if "args" in locals() else False)
+        return e.exit_code
+
+    except KeyboardInterrupt:
+        # User cancelled operation
+        output.error("\n\nOperation cancelled by user")
+        return 130
+
+    except Exception as e:
+        # Unexpected errors - show full details
+        ErrorFormatter.print_error(e, verbose=True)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

solokit/core/__init__.py

@@ -0,0 +1 @@
+"""Core functionality for Solokit including file operations, logging, and configuration."""

solokit/core/cache.py

@@ -0,0 +1,102 @@
+"""Caching layer for frequently accessed data"""
+
+import threading
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+
+class Cache:
+    """Thread-safe cache with TTL"""
+
+    def __init__(self, default_ttl: int = 300):
+        """Initialize cache with default TTL (seconds)"""
+        self.default_ttl = default_ttl
+        self._cache: dict[str, tuple[Any, datetime]] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> Optional[Any]:
+        """Get value from cache"""
+        with self._lock:
+            if key in self._cache:
+                value, expires_at = self._cache[key]
+                if datetime.now() < expires_at:
+                    return value
+                else:
+                    # Expired
+                    del self._cache[key]
+            return None
+
+    def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None:
+        """Set value in cache with TTL"""
+        ttl = ttl or self.default_ttl
+        expires_at = datetime.now() + timedelta(seconds=ttl)
+        with self._lock:
+            self._cache[key] = (value, expires_at)
+
+    def invalidate(self, key: str) -> None:
+        """Invalidate cache entry"""
+        with self._lock:
+            if key in self._cache:
+                del self._cache[key]
+
+    def clear(self) -> None:
+        """Clear all cache"""
+        with self._lock:
+            self._cache.clear()
+
+
+# Global cache instance
+_global_cache = Cache(default_ttl=60)  # 1 minute default
+
+
+def get_cache() -> Cache:
+    """Get global cache instance"""
+    return _global_cache
+
+
+class FileCache:
+    """Cache for JSON files with modification tracking"""
+
+    def __init__(self, cache: Optional[Cache] = None):
+        """Initialize file cache"""
+        self.cache = cache or get_cache()
+
+    def load_json(self, file_path: Path, loader_func: Callable[[Path], Any]) -> Any:
+        """
+        Load JSON with caching
+
+        Args:
+            file_path: Path to JSON file
+            loader_func: Function to load file if not cached
+
+        Returns:
+            Loaded data (from cache or file)
+        """
+        cache_key = f"file:{file_path}"
+
+        # Check modification time
+        if file_path.exists():
+            mtime = file_path.stat().st_mtime
+            mtime_key = f"{cache_key}:mtime"
+
+            # Check cache
+            cached_mtime = self.cache.get(mtime_key)
+            if cached_mtime == mtime:
+                cached_data = self.cache.get(cache_key)
+                if cached_data is not None:
+                    return cached_data
+
+            # Load and cache
+            data = loader_func(file_path)
+            self.cache.set(cache_key, data, ttl=300)  # 5 min TTL
+            self.cache.set(mtime_key, mtime, ttl=300)
+            return data
+        else:
+            return loader_func(file_path)
+
+    def invalidate(self, file_path: Path) -> None:
+        """Invalidate cache for file"""
+        cache_key = f"file:{file_path}"
+        self.cache.invalidate(cache_key)
+        self.cache.invalidate(f"{cache_key}:mtime")