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

teams_phone/cli/locations.py

@@ -0,0 +1,308 @@
+"""Emergency location management commands for Teams Phone CLI.
+
+This module provides CLI commands for listing, showing, and searching
+emergency locations from the CSV cache.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+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.models import EmergencyLocation
+from teams_phone.services import LocationService
+
+
+if TYPE_CHECKING:
+    from teams_phone.infrastructure import OutputFormatter
+
+locations_app = typer.Typer(
+    name="locations",
+    help="Manage emergency locations.",
+    no_args_is_help=True,
+)
+
+
+class SearchField(str, Enum):
+    """Search field options for location search."""
+
+    NAME = "name"
+    ADDRESS = "address"
+    CITY = "city"
+    COMPANY = "company"
+
+
+def _format_default(is_default: bool) -> str:
+    """Format default status for display."""
+    return "Yes" if is_default else "No"
+
+
+def _location_to_list_dict(location: EmergencyLocation) -> dict[str, Any]:
+    """Convert EmergencyLocation to dict for list/search table display."""
+    return {
+        "description": location.description or "—",
+        "address": location.address or "—",
+        "city": location.city or "—",
+        "state": location.state_or_province or "—",
+        "default": _format_default(location.is_default),
+    }
+
+
+def _location_to_json_dict(location: EmergencyLocation) -> dict[str, Any]:
+    """Convert EmergencyLocation to dict for JSON output."""
+    return {
+        "location_id": location.location_id,
+        "civic_address_id": location.civic_address_id,
+        "description": location.description,
+        "company_name": location.company_name,
+        "address": location.address,
+        "city": location.city,
+        "state_or_province": location.state_or_province,
+        "postal_code": location.postal_code,
+        "country_or_region": location.country_or_region,
+        "is_default": location.is_default,
+    }
+
+
+def _get_service() -> LocationService:
+    """Create a LocationService instance."""
+    cache_manager = CacheManager()
+    return LocationService(cache_manager)
+
+
+def _check_staleness(service: LocationService, formatter: OutputFormatter) -> None:
+    """Check for staleness warning and display if needed."""
+    staleness_warning = service.get_staleness_warning()
+    if staleness_warning:
+        formatter.warning(staleness_warning)
+
+
+def _location_matches_query(
+    loc: EmergencyLocation, query_lower: str, field: SearchField | None
+) -> bool:
+    """Check if a location matches the search query.
+
+    Args:
+        loc: The location to check.
+        query_lower: The lowercase search query.
+        field: Optional field to limit search, or None for all fields.
+
+    Returns:
+        True if the location matches the query.
+    """
+    # Define field-to-value mapping
+    field_values: dict[SearchField | None, list[str | None]] = {
+        SearchField.NAME: [loc.description],
+        SearchField.ADDRESS: [loc.address],
+        SearchField.CITY: [loc.city],
+        SearchField.COMPANY: [loc.company_name],
+        None: [loc.description, loc.address, loc.city, loc.company_name],
+    }
+
+    values_to_check = field_values.get(field, [])
+    return any(query_lower in (value or "").lower() for value in values_to_check)
+
+
+@locations_app.command("list")
+def list_locations(
+    ctx: typer.Context,
+    city: str | None = typer.Option(
+        None,
+        "--city",
+        "-c",
+        help="Filter by city.",
+    ),
+    limit: int | None = typer.Option(
+        None,
+        "--limit",
+        "-l",
+        help="Limit results to n locations.",
+    ),
+    all_locations: bool = typer.Option(
+        False,
+        "--all",
+        help="Fetch all locations (default behavior when no limit specified).",
+    ),
+) -> None:
+    """List emergency locations from CSV cache."""
+    cli_ctx = get_context(ctx)
+    formatter = cli_ctx.get_output_formatter()
+
+    # Validate mutually exclusive options
+    if limit is not None and all_locations:
+        formatter.error(
+            "Cannot specify both --limit and --all",
+            remediation="Use either --limit <n> to limit results or --all to fetch all locations.",
+        )
+        raise typer.Exit(5)  # ValidationError exit code
+
+    try:
+        service = _get_service()
+
+        # Check for staleness before output
+        _check_staleness(service, formatter)
+
+        locations = service.list_locations()
+
+        # Filter by city if specified
+        if city:
+            city_lower = city.lower()
+            locations = [
+                loc for loc in locations if (loc.city or "").lower() == city_lower
+            ]
+
+        # Apply limit if specified
+        if limit is not None:
+            locations = locations[:limit]
+
+        if cli_ctx.json_output:
+            formatter.json([_location_to_json_dict(loc) for loc in locations])
+        else:
+            if not locations:
+                formatter.info("No locations found matching the specified criteria")
+            else:
+                formatter.table(
+                    data=[_location_to_list_dict(loc) for loc in locations],
+                    columns=[
+                        "description",
+                        "address",
+                        "city",
+                        "state",
+                        "default",
+                    ],
+                    title="Emergency Locations",
+                )
+    except TeamsPhoneError as e:
+        formatter.error(e.message, remediation=e.remediation)
+        raise typer.Exit(e.exit_code) from None
+
+
+@locations_app.command("show")
+def show_location(
+    ctx: typer.Context,
+    location: str = typer.Argument(
+        ...,
+        help="Location identifier: ID (GUID) or description.",
+    ),
+) -> None:
+    """Show detailed information for a specific emergency location."""
+    cli_ctx = get_context(ctx)
+    formatter = cli_ctx.get_output_formatter()
+
+    try:
+        service = _get_service()
+
+        # Check for staleness before output
+        _check_staleness(service, formatter)
+
+        loc = service.validate_location(location)
+
+        if cli_ctx.json_output:
+            formatter.json(_location_to_json_dict(loc))
+        else:
+            # Identity section
+            formatter.table(
+                data=[
+                    {"field": "Description", "value": loc.description or "—"},
+                    {"field": "Location ID", "value": loc.location_id},
+                    {"field": "Civic Address ID", "value": loc.civic_address_id},
+                    {"field": "Company Name", "value": loc.company_name or "—"},
+                ],
+                columns=["field", "value"],
+                title="Location Details",
+            )
+
+            # Address section
+            formatter.table(
+                data=[
+                    {"field": "Street", "value": loc.address or "—"},
+                    {"field": "City", "value": loc.city or "—"},
+                    {"field": "State/Province", "value": loc.state_or_province or "—"},
+                    {"field": "Postal Code", "value": loc.postal_code or "—"},
+                    {"field": "Country", "value": loc.country_or_region or "—"},
+                ],
+                columns=["field", "value"],
+                title="Address",
+            )
+
+            # Status section
+            formatter.table(
+                data=[
+                    {
+                        "field": "Default Location",
+                        "value": _format_default(loc.is_default),
+                    },
+                ],
+                columns=["field", "value"],
+                title="Status",
+            )
+
+    except TeamsPhoneError as e:
+        formatter.error(e.message, remediation=e.remediation)
+        raise typer.Exit(e.exit_code) from None
+
+
+@locations_app.command("search")
+def search_locations(
+    ctx: typer.Context,
+    query: str = typer.Argument(
+        ...,
+        help="Search term (partial match supported, case-insensitive).",
+    ),
+    field: SearchField | None = typer.Option(
+        None,
+        "--field",
+        "-f",
+        help="Limit search to: name, address, city, company.",
+    ),
+    limit: int = typer.Option(
+        25,
+        "--limit",
+        "-l",
+        help="Maximum results (default: 25).",
+    ),
+) -> None:
+    """Search emergency locations by name, address, or city."""
+    cli_ctx = get_context(ctx)
+    formatter = cli_ctx.get_output_formatter()
+
+    try:
+        service = _get_service()
+
+        # Check for staleness before output
+        _check_staleness(service, formatter)
+
+        # Get all locations for filtered search
+        all_locs = service.list_locations()
+        query_lower = query.lower()
+
+        # Filter locations using helper function and apply limit
+        results = [
+            loc for loc in all_locs if _location_matches_query(loc, query_lower, field)
+        ][:limit]
+
+        if cli_ctx.json_output:
+            formatter.json([_location_to_json_dict(loc) for loc in results])
+        else:
+            if not results:
+                formatter.info(f"No locations found matching '{query}'")
+            else:
+                formatter.table(
+                    data=[_location_to_list_dict(loc) for loc in results],
+                    columns=[
+                        "description",
+                        "address",
+                        "city",
+                        "state",
+                        "default",
+                    ],
+                    title=f"Search Results for '{query}'",
+                )
+    except TeamsPhoneError as e:
+        formatter.error(e.message, remediation=e.remediation)
+        raise typer.Exit(e.exit_code) from None

teams_phone/cli/main.py

@@ -0,0 +1,99 @@
+"""Main Typer application for Teams Phone CLI.
+
+This module defines the root Typer app with global options (--json, --verbose,
+--tenant, --no-color) that are captured in the context for downstream commands.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from teams_phone.cli.api_check import api_check
+from teams_phone.cli.auth import auth_app
+from teams_phone.cli.context import CLIContext
+from teams_phone.cli.locations import locations_app
+from teams_phone.cli.numbers import numbers_app
+from teams_phone.cli.policies import policies_app
+from teams_phone.cli.tenants import tenants_app
+from teams_phone.cli.users import users_app
+from teams_phone.infrastructure import OutputFormatter
+from teams_phone.infrastructure.debug_logger import DebugLogger
+
+
+app = typer.Typer(
+    name="teams-phone",
+    help="Manage Microsoft Teams Phone configurations via Microsoft Graph API.",
+    no_args_is_help=True,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Output in JSON format for automation.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show detailed output and debug information.",
+    ),
+    tenant: str | None = typer.Option(
+        None,
+        "--tenant",
+        "-t",
+        help="Override default tenant for this command.",
+    ),
+    no_color: bool = typer.Option(
+        False,
+        "--no-color",
+        help="Disable color output.",
+    ),
+    debug_log: Path | None = typer.Option(
+        None,
+        "--debug-log",
+        help="Write debug logs to specified file (JSON Lines format).",
+    ),
+) -> None:
+    """Teams Phone CLI - Manage Microsoft Teams Phone configurations.
+
+    This command provides access to Teams Phone management operations including
+    user management, phone number assignment, policy configuration, and more.
+    """
+    # Create typed context with global options
+    cli_ctx = CLIContext(
+        json_output=json_output,
+        verbose=verbose,
+        tenant=tenant,
+        no_color=no_color,
+        debug_log_path=debug_log,
+    )
+    # Initialize OutputFormatter immediately (cheap operation)
+    cli_ctx.output_formatter = OutputFormatter(
+        json_mode=json_output,
+        no_color=no_color,
+    )
+    # Initialize DebugLogger if debug log path is specified
+    if debug_log is not None:
+        cli_ctx.debug_logger = DebugLogger(debug_log)
+    # ConfigManager is lazily initialized when needed to avoid disk I/O on --help
+    ctx.obj = cli_ctx
+
+
+# Register command groups with main app
+# Note: auth_app is imported from teams_phone.cli.auth
+app.add_typer(users_app, name="users", help="Manage Teams users.")
+app.add_typer(numbers_app, name="numbers", help="Manage phone numbers.")
+app.add_typer(policies_app, name="policies", help="Manage voice policies.")
+app.add_typer(locations_app, name="locations", help="Manage emergency locations.")
+app.add_typer(tenants_app, name="tenants", help="Manage tenant profiles.")
+app.add_typer(auth_app, name="auth", help="Authentication commands.")
+
+# Register standalone commands
+app.command("api-check")(api_check)