teams-phone-cli 0.1.2__py3-none-any.whl

teams_phone/__init__.py

@@ -0,0 +1,3 @@
+"""Teams Phone CLI - Manage Microsoft Teams Phone configurations."""
+
+__version__ = "0.1.0"

teams_phone/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for running as python -m teams_phone."""
+
+from teams_phone.cli.main import app
+
+
+if __name__ == "__main__":
+    app()

teams_phone/cli/__init__.py

@@ -0,0 +1,8 @@
+"""CLI Layer - Typer commands for Teams Phone management."""
+
+from teams_phone.cli.context import CLIContext, get_context
+from teams_phone.cli.helpers import run_with_service
+from teams_phone.cli.main import app
+
+
+__all__ = ["CLIContext", "app", "get_context", "run_with_service"]

teams_phone/cli/api_check.py

@@ -0,0 +1,267 @@
+"""API contract validation command for Teams Phone CLI.
+
+This module provides the api-check command for validating Pydantic models
+against live Graph API responses to detect API contract drift.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any
+
+import typer
+from pydantic import ValidationError
+
+from teams_phone.cli.context import get_context
+from teams_phone.constants import ExitCode
+from teams_phone.exceptions import TeamsPhoneError
+from teams_phone.infrastructure import CacheManager, GraphClient
+from teams_phone.models import NumberAssignment, UserConfiguration
+from teams_phone.services import AuthService
+
+
+@dataclass
+class EndpointCheck:
+    """Configuration for an endpoint contract check."""
+
+    name: str
+    endpoint: str
+    model_name: str
+    validator: Any  # Pydantic model class
+
+
+@dataclass
+class CheckResult:
+    """Result of a single endpoint validation check."""
+
+    endpoint_name: str
+    passed: bool
+    error_message: str | None = None
+    error_details: list[str] | None = None
+
+
+# Define endpoints to check
+ENDPOINT_CHECKS = [
+    EndpointCheck(
+        name="userConfigurations",
+        endpoint="/admin/teams/userConfigurations",
+        model_name="UserConfiguration",
+        validator=UserConfiguration,
+    ),
+    EndpointCheck(
+        name="numberAssignments",
+        endpoint="/admin/teams/telephoneNumberManagement/numberAssignments",
+        model_name="NumberAssignment",
+        validator=NumberAssignment,
+    ),
+]
+
+
+def _strip_odata_metadata(data: dict[str, Any]) -> dict[str, Any]:
+    """Strip OData metadata fields from a response dict.
+
+    Graph API responses include @odata.context and other @ prefixed fields
+    that are not part of the actual data contract. This helper removes them
+    before Pydantic validation with extra="forbid".
+    """
+    return {k: v for k, v in data.items() if not k.startswith("@")}
+
+
+async def _validate_endpoint(
+    graph_client: GraphClient,
+    check: EndpointCheck,
+) -> CheckResult:
+    """Validate a single endpoint against its Pydantic model.
+
+    Args:
+        graph_client: Authenticated Graph API client.
+        check: Endpoint configuration to validate.
+
+    Returns:
+        CheckResult with pass/fail status and any error details.
+    """
+    try:
+        # Fetch a single sample item from the endpoint
+        response = await graph_client.get(check.endpoint, params={"$top": "1"})
+
+        # Extract items from the list response
+        items = response.get("value", [])
+
+        if not items:
+            # No data to validate - that's still a pass, just nothing to check
+            return CheckResult(
+                endpoint_name=check.name,
+                passed=True,
+                error_message="No data available for validation",
+            )
+
+        # Validate each item against the model
+        for item in items:
+            cleaned = _strip_odata_metadata(item)
+            check.validator.model_validate(cleaned)
+
+        return CheckResult(endpoint_name=check.name, passed=True)
+
+    except ValidationError as e:
+        # Extract error details for verbose output
+        error_details = []
+        for error in e.errors():
+            loc = ".".join(str(part) for part in error["loc"])
+            msg = error["msg"]
+            error_type = error["type"]
+            error_details.append(f"  - {loc}: {msg} (type: {error_type})")
+
+        return CheckResult(
+            endpoint_name=check.name,
+            passed=False,
+            error_message=f"Schema validation failed for {check.model_name}",
+            error_details=error_details,
+        )
+
+    except TeamsPhoneError as e:
+        # API errors (auth, rate limit, etc.)
+        return CheckResult(
+            endpoint_name=check.name,
+            passed=False,
+            error_message=f"API error: {e.message}",
+        )
+
+
+async def _run_validation(
+    auth_service: AuthService,
+    endpoint_filter: str | None,
+) -> list[CheckResult]:
+    """Run validation checks against Graph API endpoints.
+
+    Args:
+        auth_service: Authenticated service for API access.
+        endpoint_filter: Optional endpoint name to check (None = all endpoints).
+
+    Returns:
+        List of CheckResult for each endpoint checked.
+    """
+    # Filter endpoints if specific one requested
+    checks = ENDPOINT_CHECKS
+    if endpoint_filter:
+        checks = [c for c in ENDPOINT_CHECKS if c.name == endpoint_filter]
+
+    results: list[CheckResult] = []
+
+    async with GraphClient(auth_service) as graph_client:
+        for check in checks:
+            result = await _validate_endpoint(graph_client, check)
+            results.append(result)
+
+    return results
+
+
+def api_check(  # noqa: C901 - CLI command with validation, table/JSON output, and verbose mode
+    ctx: typer.Context,
+    endpoint: str | None = typer.Option(
+        None,
+        "--endpoint",
+        "-e",
+        help="Check specific endpoint (userConfigurations, numberAssignments).",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-V",
+        help="Show detailed validation error output.",
+    ),
+) -> None:
+    """Validate API contracts against live Graph API responses.
+
+    Fetches sample data from Graph API endpoints and validates against
+    Pydantic models with strict mode (extra="forbid") to detect API
+    contract drift (new fields, renamed fields, removed fields).
+
+    Exits with code 8 (CONTRACT_ERROR) if any validation failures.
+    """
+    cli_ctx = get_context(ctx)
+    formatter = cli_ctx.get_output_formatter()
+
+    try:
+        config_manager = cli_ctx.get_config_manager()
+        cache_manager = CacheManager()
+        auth_service = AuthService(config_manager, cache_manager)
+
+        # Validate endpoint filter if provided
+        valid_endpoints = [c.name for c in ENDPOINT_CHECKS]
+        if endpoint and endpoint not in valid_endpoints:
+            formatter.error(
+                f"Unknown endpoint: {endpoint}",
+                remediation=f"Valid endpoints: {', '.join(valid_endpoints)}",
+            )
+            raise typer.Exit(ExitCode.VALIDATION_ERROR)
+
+        # Run validation
+        results = asyncio.run(_run_validation(auth_service, endpoint))
+
+        # Handle no endpoints scenario
+        if not results:
+            formatter.warning("No endpoints to check")
+            raise typer.Exit(ExitCode.SUCCESS)
+
+        # Determine overall status
+        all_passed = all(r.passed for r in results)
+        failures = [r for r in results if not r.passed]
+
+        # Output results
+        if cli_ctx.json_output:
+            formatter.json(
+                {
+                    "status": "pass" if all_passed else "fail",
+                    "results": [
+                        {
+                            "endpoint": r.endpoint_name,
+                            "status": "PASS" if r.passed else "FAIL",
+                            "error": r.error_message,
+                            "details": r.error_details,
+                        }
+                        for r in results
+                    ],
+                }
+            )
+        else:
+            # Display results table
+            table_data = []
+            for result in results:
+                row = {
+                    "endpoint": result.endpoint_name,
+                    "status": "PASS" if result.passed else "FAIL",
+                    "error": result.error_message or "—",
+                }
+                table_data.append(row)
+
+            formatter.table(
+                data=table_data,
+                columns=["endpoint", "status", "error"],
+                title="API Contract Validation Results",
+            )
+
+            # Show detailed errors if verbose mode and there are failures
+            if verbose and failures:
+                for result in failures:
+                    if result.error_details:
+                        formatter.info(f"\nDetails for {result.endpoint_name}:")
+                        for detail in result.error_details:
+                            formatter.info(f"  {detail}")
+
+            if all_passed:
+                formatter.success(
+                    f"All {len(results)} endpoint(s) validated successfully"
+                )
+            else:
+                formatter.error(
+                    f"{len(failures)} of {len(results)} endpoint(s) failed validation"
+                )
+
+        # Exit with appropriate code
+        if not all_passed:
+            raise typer.Exit(ExitCode.CONTRACT_ERROR)
+
+    except TeamsPhoneError as e:
+        formatter.error(e.message, remediation=e.remediation)
+        raise typer.Exit(e.exit_code) from None

teams_phone/cli/auth.py

@@ -0,0 +1,201 @@
+"""Authentication commands for Teams Phone CLI.
+
+This module provides CLI commands for authenticating with Microsoft Entra ID,
+managing tokens, and checking authentication status.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from teams_phone.cli.context import get_context
+from teams_phone.exceptions import TeamsPhoneError
+from teams_phone.infrastructure import CacheManager
+from teams_phone.services import AuthService
+
+
+auth_app = typer.Typer(
+    name="auth",
+    help="Authentication commands.",
+    no_args_is_help=True,
+)
+
+
+@auth_app.command()
+def status(ctx: typer.Context) -> None:
+    """Show current authentication status."""
+    cli_ctx = get_context(ctx)
+    formatter = cli_ctx.get_output_formatter()
+
+    try:
+        config_manager = cli_ctx.get_config_manager()
+        cache_manager = CacheManager()
+        auth_service = AuthService(config_manager, cache_manager)
+
+        tenant_name = cli_ctx.tenant
+        auth_status = auth_service.get_status(tenant_name)
+
+        if cli_ctx.json_output:
+            formatter.json(auth_status.model_dump(mode="json"))
+        else:
+            table_data = [
+                {"field": "Status", "value": auth_status.status.value},
+            ]
+            if auth_status.tenant_name:
+                table_data.append({"field": "Tenant", "value": auth_status.tenant_name})
+            if auth_status.tenant_id:
+                table_data.append(
+                    {"field": "Tenant ID", "value": auth_status.tenant_id}
+                )
+            if auth_status.expires_at:
+                table_data.append(
+                    {"field": "Expires at", "value": auth_status.expires_at.isoformat()}
+                )
+            formatter.table(
+                data=table_data,
+                columns=["field", "value"],
+                title="Authentication Status",
+            )
+    except TeamsPhoneError as e:
+        formatter.error(e.message, remediation=e.remediation)
+        raise typer.Exit(e.exit_code) from None
+
+
+@auth_app.command()
+def login(
+    ctx: typer.Context,
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Force new authentication even if token exists.",
+    ),
+) -> None:
+    """Authenticate with the current tenant."""
+    cli_ctx = get_context(ctx)
+    formatter = cli_ctx.get_output_formatter()
+
+    try:
+        config_manager = cli_ctx.get_config_manager()
+        cache_manager = CacheManager()
+        auth_service = AuthService(config_manager, cache_manager)
+
+        tenant_name = cli_ctx.tenant
+        token = auth_service.login(tenant_name, force=force)
+
+        if cli_ctx.json_output:
+            formatter.json(
+                {
+                    "status": "authenticated",
+                    "tenant_id": token.tenant_id,
+                    "expires_at": token.expires_at.isoformat(),
+                }
+            )
+        else:
+            formatter.success("Successfully authenticated")
+            formatter.info(f"Tenant ID: {token.tenant_id}")
+            formatter.info(f"Token expires at: {token.expires_at.isoformat()}")
+    except TeamsPhoneError as e:
+        formatter.error(e.message, remediation=e.remediation)
+        raise typer.Exit(e.exit_code) from None
+
+
+@auth_app.command()
+def logout(
+    ctx: typer.Context,
+    all_tenants: bool = typer.Option(
+        False,
+        "--all",
+        "-a",
+        help="Clear tokens for all tenants.",
+    ),
+) -> None:
+    """Clear cached authentication tokens."""
+    cli_ctx = get_context(ctx)
+    formatter = cli_ctx.get_output_formatter()
+
+    try:
+        config_manager = cli_ctx.get_config_manager()
+        cache_manager = CacheManager()
+        auth_service = AuthService(config_manager, cache_manager)
+
+        tenant_name = cli_ctx.tenant
+        auth_service.logout(tenant_name, all_tenants=all_tenants)
+
+        if cli_ctx.json_output:
+            if all_tenants:
+                formatter.json({"status": "logged_out", "all_tenants": True})
+            else:
+                formatter.json({"status": "logged_out", "tenant": tenant_name})
+        else:
+            if all_tenants:
+                formatter.success("Logged out from all tenants")
+            else:
+                tenant_display = tenant_name or "default tenant"
+                formatter.success(f"Logged out from {tenant_display}")
+    except TeamsPhoneError as e:
+        formatter.error(e.message, remediation=e.remediation)
+        raise typer.Exit(e.exit_code) from None
+
+
+@auth_app.command()
+def refresh(
+    ctx: typer.Context,
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Force refresh even if token is still valid.",
+    ),
+) -> None:
+    """Refresh cached authentication tokens."""
+    cli_ctx = get_context(ctx)
+    formatter = cli_ctx.get_output_formatter()
+
+    try:
+        config_manager = cli_ctx.get_config_manager()
+        cache_manager = CacheManager()
+        auth_service = AuthService(config_manager, cache_manager)
+
+        tenant_name = cli_ctx.tenant
+
+        if force:
+            token = auth_service.refresh_token(tenant_name)
+        else:
+            # Check if token needs refresh before doing it
+            auth_status = auth_service.get_status(tenant_name)
+            from teams_phone.models import AuthStatusType
+
+            if auth_status.status == AuthStatusType.AUTHENTICATED:
+                if cli_ctx.json_output:
+                    formatter.json(
+                        {
+                            "status": "already_valid",
+                            "tenant_id": auth_status.tenant_id,
+                            "expires_at": auth_status.expires_at.isoformat()
+                            if auth_status.expires_at
+                            else None,
+                        }
+                    )
+                else:
+                    formatter.info("Token is still valid, no refresh needed")
+                    formatter.info("Use --force to refresh anyway")
+                return
+
+            token = auth_service.refresh_token(tenant_name)
+
+        if cli_ctx.json_output:
+            formatter.json(
+                {
+                    "status": "refreshed",
+                    "tenant_id": token.tenant_id,
+                    "expires_at": token.expires_at.isoformat(),
+                }
+            )
+        else:
+            formatter.success("Token refreshed successfully")
+            formatter.info(f"Tenant ID: {token.tenant_id}")
+            formatter.info(f"Token expires at: {token.expires_at.isoformat()}")
+    except TeamsPhoneError as e:
+        formatter.error(e.message, remediation=e.remediation)
+        raise typer.Exit(e.exit_code) from None

teams_phone/cli/context.py

@@ -0,0 +1,108 @@
+"""CLI context for type-safe access to global options and services.
+
+This module provides the CLIContext dataclass that replaces the raw dict
+used in ctx.obj, enabling type-safe access to global options and lazy
+initialization of services like ConfigManager and OutputFormatter.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import typer
+
+
+if TYPE_CHECKING:
+    from teams_phone.infrastructure import ConfigManager, OutputFormatter
+    from teams_phone.infrastructure.debug_logger import DebugLogger
+
+
+@dataclass
+class CLIContext:
+    """Type-safe context for CLI commands.
+
+    Stores global options and provides lazy access to services.
+
+    Attributes:
+        json_output: Output in JSON format for automation.
+        verbose: Enable verbose output and debug information.
+        tenant: Tenant name override (None = use default from config).
+        no_color: Disable colored output.
+        debug_log_path: Path for debug log file (None = disabled).
+        config_manager: Lazily initialized ConfigManager instance.
+        output_formatter: Initialized OutputFormatter for output.
+        debug_logger: Initialized DebugLogger for debug logging.
+    """
+
+    json_output: bool = False
+    verbose: bool = False
+    tenant: str | None = None
+    no_color: bool = False
+    debug_log_path: Path | None = None
+    config_manager: ConfigManager | None = None
+    output_formatter: OutputFormatter | None = None
+    debug_logger: DebugLogger | None = None
+
+    def get_output_formatter(self) -> OutputFormatter:
+        """Get or create the OutputFormatter.
+
+        Creates an OutputFormatter on first access using the json_output
+        and no_color settings from this context.
+
+        Returns:
+            The OutputFormatter instance.
+        """
+        if self.output_formatter is None:
+            from teams_phone.infrastructure import OutputFormatter
+
+            self.output_formatter = OutputFormatter(
+                json_mode=self.json_output,
+                no_color=self.no_color,
+            )
+        return self.output_formatter
+
+    def get_config_manager(self) -> ConfigManager:
+        """Get or create the ConfigManager.
+
+        Creates a ConfigManager on first access. This defers disk I/O
+        until actually needed, avoiding unnecessary config file reads
+        on operations like --help.
+
+        Returns:
+            The ConfigManager instance.
+        """
+        if self.config_manager is None:
+            from teams_phone.infrastructure import ConfigManager
+
+            self.config_manager = ConfigManager()
+        return self.config_manager
+
+    def get_debug_logger(self) -> DebugLogger | None:
+        """Get the DebugLogger if debug logging is enabled.
+
+        Returns:
+            The DebugLogger instance if debug_log_path is set, None otherwise.
+        """
+        return self.debug_logger
+
+
+def get_context(ctx: typer.Context) -> CLIContext:
+    """Retrieve typed CLIContext from Typer context.
+
+    Args:
+        ctx: The Typer/Click context object.
+
+    Returns:
+        The CLIContext instance stored in ctx.obj.
+
+    Raises:
+        RuntimeError: If ctx.obj is not a CLIContext (programming error).
+    """
+    if not isinstance(ctx.obj, CLIContext):
+        raise RuntimeError(
+            "CLIContext not found in context. "
+            "This is a programming error - ensure the main callback ran."
+        )
+    return ctx.obj

teams_phone/cli/helpers.py

@@ -0,0 +1,65 @@
+"""CLI Helper Functions - Shared utilities for CLI commands."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, TypeVar
+
+import typer
+
+from teams_phone.cli.context import get_context
+from teams_phone.infrastructure import CacheManager, GraphClient
+from teams_phone.services import AuthService
+
+
+if TYPE_CHECKING:
+    from teams_phone.infrastructure import OutputFormatter
+
+ServiceT = TypeVar("ServiceT")
+
+
+def run_with_service(
+    ctx: typer.Context,
+    service_factory: Callable[[GraphClient], ServiceT],
+    operation: Callable[[ServiceT], Any],
+) -> tuple[Any, OutputFormatter]:
+    """Run an async operation with a service.
+
+    Creates the required infrastructure (GraphClient, service) and runs
+    the async operation using asyncio.run(). This is the generic pattern
+    for CLI commands that need to interact with services.
+
+    Args:
+        ctx: Typer context with CLIContext.
+        service_factory: A callable that takes a GraphClient and returns
+            a service instance (e.g., UserService, NumberService).
+        operation: A callable that takes the service and returns a coroutine
+            to execute.
+
+    Returns:
+        Tuple of (result, OutputFormatter) where result is the coroutine's
+        return value.
+
+    Example:
+        def list_users(ctx: typer.Context) -> None:
+            result, formatter = run_with_service(
+                ctx,
+                service_factory=UserService,
+                operation=lambda svc: svc.list_users(),
+            )
+            formatter.print_table(result)
+    """
+    cli_ctx = get_context(ctx)
+    formatter = cli_ctx.get_output_formatter()
+    config_manager = cli_ctx.get_config_manager()
+    cache_manager = CacheManager()
+    auth_service = AuthService(config_manager, cache_manager)
+
+    async def _execute() -> Any:
+        async with GraphClient(auth_service) as graph_client:
+            service = service_factory(graph_client)
+            return await operation(service)
+
+    result = asyncio.run(_execute())
+    return result, formatter