roadmap-cli 0.1.1__py3-none-any.whl

roadmap/__init__.py

@@ -0,0 +1,27 @@
+"""Roadmap CLI - A command line tool for creating and managing roadmaps."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+# Define version BEFORE importing cli modules (they import __version__ from here)
+# Keep a source-checkout fallback for direct imports. Installed wheels and sdists
+# obtain the authoritative version from their distribution metadata because the
+# repository-level pyproject.toml is not part of an installed wheel.
+__version__ = "0.1.1"
+try:
+    __version__ = version("roadmap-cli")
+except PackageNotFoundError:
+    __version__ = "0.1.1"
+
+# Now import cli (which will import __version__ from this module)
+from roadmap.adapters import cli  # noqa: F401, E402
+
+# Legacy exports - use layer-specific imports instead
+# from roadmap.core.domain import Issue, Milestone
+# from roadmap.adapters.github.github import GitHubClient
+# from roadmap.infrastructure.security.credentials import CredentialManager
+# from roadmap.core.services import ... etc
+
+__all__ = [
+    "__version__",
+    "cli",
+]

roadmap/adapters/__init__.py

@@ -0,0 +1 @@
+"""External system adapters for GitHub, Git, and synchronization."""

roadmap/adapters/base_paginated_adapter.py

@@ -0,0 +1,117 @@
+"""Base adapter for REST APIs with pagination support.
+
+This module provides a reusable foundation for API adapters that implement
+pagination. Any backend (GitHub, GitLab, etc.) that needs to paginate through
+REST API results should inherit from this class.
+
+The pagination implementation is backend-agnostic - it works with any REST API
+that follows standard pagination patterns (page number, per_page, Link headers).
+"""
+
+from typing import Any
+
+from structlog import get_logger
+
+logger = get_logger(__name__)
+
+
+class BasePaginatedAdapter:
+    """Base class for REST API adapters with pagination support.
+
+    Provides a reusable `_paginate_request()` method that handles pagination
+    for any REST API endpoint. Backends should inherit from this class to
+    automatically get pagination capability.
+
+    Subclasses must implement `_make_request()` to perform actual API calls.
+    """
+
+    def _make_request(self, method: str, endpoint: str, **kwargs) -> Any:
+        """Make a request to the API (must be implemented by subclass).
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint path
+            **kwargs: Additional arguments (params, json, headers, etc.)
+
+        Returns:
+            Response object with .json() method and .headers dict
+
+        Raises:
+            Subclass-specific exception on error
+        """
+        raise NotImplementedError("Subclasses must implement _make_request()")
+
+    def _paginate_request(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict | None = None,
+        per_page: int = 100,
+    ) -> list[dict[str, Any]]:
+        """Make a paginated request to a REST API.
+
+        Automatically handles pagination by checking the Link header
+        for next page references. Returns all items across all pages.
+
+        This method is backend-agnostic and works with any REST API that:
+        1. Supports page and per_page query parameters
+        2. Returns a Link header with rel="next" for pagination
+        3. Returns an empty list when no more items exist
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint path
+            params: Query parameters (will add page and per_page)
+            per_page: Items per page (backend default is usually 30-100)
+
+        Returns:
+            List of all items from all pages (flattened)
+
+        Raises:
+            Subclass-specific exceptions if any request fails
+        """
+        all_items = []
+        page = 1
+        params = params or {}
+
+        while True:
+            # Add pagination params
+            page_params = {**params, "page": page, "per_page": per_page}
+
+            response = self._make_request(method, endpoint, params=page_params)
+            items_page = response.json()
+
+            if not items_page:
+                # No more items on this page
+                logger.debug(
+                    "pagination_complete",
+                    endpoint=endpoint,
+                    total_pages=page - 1,
+                    total_items=len(all_items),
+                )
+                break
+
+            all_items.extend(items_page)
+            logger.debug(
+                "pagination_page_fetched",
+                endpoint=endpoint,
+                page=page,
+                page_count=len(items_page),
+                total_so_far=len(all_items),
+            )
+
+            # Check if there are more pages by looking at the Link header
+            link_header = response.headers.get("Link", "")
+            if 'rel="next"' not in link_header:
+                # No next page link, we're done
+                logger.debug(
+                    "pagination_no_next_link",
+                    endpoint=endpoint,
+                    final_page=page,
+                    total_items=len(all_items),
+                )
+                break
+
+            page += 1
+
+        return all_items

roadmap/adapters/cli/__init__.py

@@ -0,0 +1,249 @@
+"""Modular CLI architecture for the Roadmap tool.
+
+This module provides the main CLI entry point and implements plugin-style
+lazy-loading of command groups to improve performance and maintainability.
+
+## Architecture
+
+Commands are registered via a plugin registry that specifies:
+- Command name/group name
+- Module path where the command is defined
+- Variable name of the command in that module
+
+This allows commands to be imported only when actually invoked, reducing
+startup time and improving modularity.
+"""
+
+import importlib
+from typing import Any
+
+import click
+
+from roadmap import __version__
+from roadmap.adapters.cli.exception_handler import handle_cli_exception
+
+# Initialize console for rich output
+from roadmap.common.console import get_console
+from roadmap.common.errors.exceptions import RoadmapException
+
+# Initialize OpenTelemetry tracing
+from roadmap.common.observability.otel_init import initialize_tracing
+
+# Import core classes for backward compatibility with tests
+from roadmap.infrastructure.coordination.core import RoadmapCore
+
+console = get_console()
+
+# Plugin registry: maps command names to their import locations
+# Format: "command_name": ("module_path", "variable_name")
+# This allows lazy loading of commands - they're only imported when invoked
+_COMMAND_REGISTRY: dict[str, tuple[str, str]] = {
+    # Core v1.0 standalone commands
+    "init": ("roadmap.adapters.cli.core", "init"),
+    "status": ("roadmap.adapters.cli.core", "status"),
+    "health": ("roadmap.adapters.cli.core", "health"),
+    "today": ("roadmap.adapters.cli.today", "today"),
+    "cleanup": ("roadmap.infrastructure.maintenance", "cleanup"),
+    # Command groups
+    "analysis": ("roadmap.adapters.cli.analysis", "analysis"),
+    "comment": ("roadmap.adapters.cli.comment", "comment"),
+    "config": ("roadmap.adapters.cli.config", "config"),
+    "data": ("roadmap.adapters.cli.data", "data"),
+    "git": ("roadmap.adapters.cli.git", "git"),
+    "issue": ("roadmap.adapters.cli.issues", "issue"),
+    "milestone": ("roadmap.adapters.cli.milestones", "milestone"),
+    "project": ("roadmap.adapters.cli.projects", "project"),
+    "sync": ("roadmap.adapters.cli.sync", "sync"),
+    "validate-links": ("roadmap.adapters.cli.sync_validation", "validate_links"),
+}
+
+# Cache for loaded commands to avoid re-importing
+_command_cache: dict[str, Any] = {}
+
+
+def _load_command(command_name: str) -> Any:
+    """Lazily load a command from the registry.
+
+    Args:
+        command_name: Name of command to load
+
+    Returns:
+        The Click command/group object
+
+    Raises:
+        ValueError: If command not found in registry
+    """
+    if command_name in _command_cache:
+        return _command_cache[command_name]
+
+    if command_name not in _COMMAND_REGISTRY:
+        raise ValueError(f"Unknown command: {command_name}")
+
+    module_path, var_name = _COMMAND_REGISTRY[command_name]
+    module = importlib.import_module(module_path)
+    command = getattr(module, var_name)
+
+    _command_cache[command_name] = command
+    return command
+
+
+# Flag to track if commands have been registered to avoid duplicate registration
+_commands_registered = False
+
+
+class RoadmapClickGroup(click.Group):
+    """Custom Click Group that handles RoadmapException instances."""
+
+    def invoke(self, ctx: click.Context) -> click.Context | None:
+        """Invoke the group with centralized exception handling."""
+        try:
+            # Allow Click to handle help and version flags normally
+            result = super().invoke(ctx)
+            return result
+        except RoadmapException as exc:
+            # Handle roadmap exceptions with our formatter
+            handle_cli_exception(ctx, exc, show_traceback=False)
+        except click.exceptions.Exit:
+            # Let Click Exit exceptions propagate (--help, --version)
+            raise
+        except click.ClickException:
+            # Let Click exceptions propagate
+            raise
+        except click.Abort:
+            # Let Click Abort propagate
+            raise
+        except SystemExit:
+            # Let SystemExit propagate (used by Click for --help, --version, etc.)
+            raise
+        except Exception as exc:
+            # Handle unexpected exceptions
+            handle_cli_exception(ctx, exc, show_traceback=False)
+
+
+# Import utility functions that tests need
+try:
+    import git as gitpython
+except ImportError:
+    gitpython = None
+
+
+def _get_current_user():
+    """Get current user from git config."""
+    if gitpython is None:
+        import os
+
+        return os.environ.get("USER") or os.environ.get("USERNAME")
+
+    try:
+        repo = gitpython.Repo(search_parent_directories=True)  # type: ignore[attr-defined]
+        try:
+            name = repo.config_reader().get_value("user", "name")
+            return name
+        except Exception as e:
+            from roadmap.common.logging import get_logger
+
+            logger = get_logger(__name__)
+            logger.debug(
+                "git_user_name_read_failed", error=str(e), action="get_git_user_name"
+            )
+    except Exception as e:
+        from roadmap.common.logging import get_logger
+
+        logger = get_logger(__name__)
+        logger.debug("git_repo_open_failed", error=str(e), action="detect_git_repo")
+
+    # Fallback to environment variables
+    import os
+
+    return os.environ.get("USER") or os.environ.get("USERNAME")
+
+
+def _detect_project_context():
+    """Detect project context from current directory."""
+    import pathlib
+
+    context = {
+        "project_name": pathlib.Path.cwd().name,
+        "has_git": False,
+    }
+
+    # Check if we're in a git repository
+    if gitpython is not None:
+        try:
+            gitpython.Repo(search_parent_directories=True)  # type: ignore[attr-defined]
+            context["has_git"] = True
+        except Exception as e:
+            from roadmap.common.logging import get_logger
+
+            logger = get_logger(__name__)
+            logger.debug(
+                "git_repo_detection_failed",
+                error=str(e),
+                action="detect_project_context",
+            )
+
+    return context
+
+
+@click.group(cls=RoadmapClickGroup)
+@click.version_option(version=__version__)
+@click.pass_context
+def main(ctx: click.Context):
+    """Roadmap CLI - A command line tool for creating and managing roadmaps."""
+    # Initialize OpenTelemetry tracing
+    initialize_tracing()
+
+    # Ensure that ctx.obj exists and is a dict (in case `cli()` is called
+    # by means other than the `if` block below)
+    ctx.ensure_object(dict)
+
+    # Initialize core with default roadmap directory (skip for init command)
+    if ctx.invoked_subcommand != "init":
+        try:
+            ctx.obj["core"] = RoadmapCore()
+        except Exception as exc:
+            # Handle exceptions during core initialization
+            handle_cli_exception(ctx, exc, show_traceback=False)
+
+    # If no subcommand was provided, show help
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+def register_commands():
+    """Register all commands from the plugin registry.
+
+    Commands are loaded lazily from the registry, which maps command names
+    to their module paths. This approach:
+    - Reduces startup time by deferring imports
+    - Makes it easy to add/remove commands
+    - Provides a single source of truth for command list
+    """
+    for command_name, _ in _COMMAND_REGISTRY.items():
+        try:
+            command = _load_command(command_name)
+            main.add_command(command, name=command_name)
+        except Exception as e:
+            console.print(
+                f"⚠️  Failed to register command '{command_name}': {e}", style="yellow"
+            )
+
+
+# Register commands at module load time
+# This ensures CLI commands are available for tests and direct usage
+try:
+    register_commands()
+    _commands_registered = True
+except ImportError as e:
+    # If there's a circular import, commands will still be registered
+    # when main() is invoked through Click's mechanism
+    if "partially initialized" not in str(e):
+        # Re-raise if it's not a circular import issue
+        raise
+    else:
+        # For circular imports, we'll register commands lazily when needed
+        _commands_registered = False
+
+
+if __name__ == "__main__":
+    main()  # type: ignore[call-arg]

roadmap/adapters/cli/analysis/__init__.py

@@ -0,0 +1,5 @@
+"""Analysis commands module."""
+
+from .commands import analysis
+
+__all__ = ["analysis"]