wxcli 1.2.0__py3-none-any.whl

wxcli/migration/phone_models.py

@@ -0,0 +1,50 @@
+"""Shared phone model constants for the CUCM migration pipeline.
+
+Single source of truth for phone model classifications used across transform
+mappers, analyzers, and execution handlers. This module has NO dependencies on
+other migration code to avoid circular imports — it exports only plain data
+(a set and two dicts).
+
+Consumers:
+    - ``transform/mappers/device_mapper.py`` — cloud vs telephony surface
+    - ``transform/mappers/softkey_mapper.py`` — PSK capability
+    - ``transform/mappers/button_template_mapper.py`` — line key counts
+    - ``transform/analyzers/layout_overflow.py`` — line key overflow detection
+    - ``execute/handlers.py`` — PhoneOS model normalization + KEM overflow split
+"""
+from __future__ import annotations
+
+# PhoneOS phones (9800-series + 8875) are distinct from classic MPP in three ways:
+#   1. They use cloud deviceId (not callingDeviceId) — device_id_surface="cloud".
+#   2. Their model strings in the Webex API drop the "DMS " prefix
+#      ("Cisco 9841" not "DMS Cisco 9841").
+#   3. They support Programmable Softkeys (PSK).
+PHONEOS_MODEL_NUMBERS: set[str] = {
+    "9811", "9821", "9841", "9851", "9861", "9871", "8875",
+}
+
+# Max physical line-key count per phone model. Buttons beyond this count are
+# KEM (Key Expansion Module) keys on KEM-capable models. Superset of the
+# PhoneOS-only counts used by handlers.py — classic MPP models (7800/8800/6800)
+# appear here for the mappers/analyzers that classify button templates.
+MODEL_LINE_KEY_COUNTS: dict[str, int] = {
+    # 7800-series
+    "7821": 2, "7841": 4, "7861": 16,
+    # 8800-series (classic MPP)
+    "8811": 10, "8832": 0, "8841": 10, "8845": 10,
+    "8851": 10, "8861": 10, "8865": 10,
+    # 8875 (PhoneOS)
+    "8875": 10,
+    # 9800-series (PhoneOS)
+    "9811": 2, "9821": 2, "9841": 4,
+    "9851": 10, "9861": 16, "9871": 32,
+    # 6800-series
+    "6821": 2, "6841": 4, "6851": 12, "6861": 16, "6871": 10,
+}
+
+# PhoneOS-only subset of the above, used by handlers.py to split KEM overflow
+# from line_keys during line-key-template execution. Derived from the superset
+# so there is exactly one place where counts are authored.
+PHONEOS_LINE_KEY_COUNTS: dict[str, int] = {
+    model: MODEL_LINE_KEY_COUNTS[model] for model in PHONEOS_MODEL_NUMBERS
+}

wxcli/migration/preflight/CLAUDE.md

@@ -0,0 +1,52 @@
+# src/wxcli/migration/preflight/
+
+Preflight checks that verify the Webex org is ready for the migration plan. Read-only — queries Webex via wxcli CLI subprocess calls, never modifies anything.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `__init__.py` | Data models (CheckStatus, CheckResult, PreflightResult, PreflightIssue, PreflightError), `_run_wxcli()` subprocess helper, `preflight_fingerprint()` |
+| `checks.py` | 8 check functions — each takes store + fetched data, returns CheckResult (or tuple with decisions) |
+| `runner.py` | PreflightRunner — fetches shared Webex data once, runs all checks, merges decisions |
+
+## Architecture
+
+```
+wxcli cucm preflight
+  → PreflightRunner.run()
+    → _fetch() shared data (licenses, locations, numbers, people, trunks)
+    → run 8 checks as pure functions of (store, fetched_data)
+    → merge NUMBER_CONFLICT + DUPLICATE_USER decisions into store
+    → return PreflightResult (overall PASS/WARN/FAIL/SKIP)
+```
+
+## The 9 Checks
+
+1. **User licenses** — enough Calling Professional licenses
+2. **Workspace licenses** — enough Workspace licenses (matches API's `UserLicenseType.WORKSPACE`)
+3. **Locations** — target locations exist in Webex + PSTN connection check per location
+4. **Trunks** — no trunk name conflicts
+5. **Feature entitlements** — AA/CQ/HG/Paging within known limits
+6. **Number conflicts** — E.164 and extension collisions (produces NUMBER_CONFLICT decisions, skips same-owner)
+7. **Duplicate users** — planned users already in Webex (produces DUPLICATE_USER decisions, 3 scenarios)
+8. **Rate limit budget** — estimated migration duration from plan_operations
+9. **E911 readiness** — Every user has a resolvable ECBN candidate (DIRECT_LINE or LOCATION_ECBN); no unresolved E911 decisions; extension-only users warn, missing candidates fail.
+
+## Key Design Decisions
+
+- **Subprocess, not import** — Checks call `wxcli` via subprocess to reuse CLI auth, pagination, error handling
+- **Scoped merge** — `merge_decisions(decision_types=["NUMBER_CONFLICT", "DUPLICATE_USER"], stage="preflight")` prevents stale-marking analyzer decisions
+- **Same-owner dedup** — NUMBER_CONFLICT skips collisions where the existing owner has the same email as the planned user
+- **Gated fetches** — When `--check` filter is set, only fetch the data needed for that check
+- **Re-runnable** — State machine allows `PREFLIGHT → PREFLIGHT` and `PREFLIGHT_FAILED → PREFLIGHT`
+
+## Tests
+
+- `tests/migration/preflight/test_checks.py` — 38 unit tests for all check functions
+- `tests/migration/preflight/test_runner.py` — 14 integration tests (mocked wxcli)
+
+## Known Limitations
+
+- PSTN connection check calls `wxcli pstn list-connection` per location — produces WARN (not FAIL) for locations without PSTN
+- ~~`wxcli users list` callingData limitation~~ — FIXED: `users` is now an alias for the generated `people` command group, and the preflight runner passes `--calling-data true`

wxcli/migration/preflight/__init__.py

@@ -0,0 +1,89 @@
+"""Preflight checks for CUCM-to-Webex migration.
+
+Verifies the Webex org is ready for the migration plan by running
+read-only checks against live Webex data via wxcli CLI commands.
+
+(from 05a-preflight-checks.md — 7 checks + DUPLICATE_USER detection)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class CheckStatus(str, Enum):
+    """Result status for a single preflight check.
+    (from 05a-preflight-checks.md, PASS/WARN/FAIL model)
+    """
+    PASS = "PASS"
+    WARN = "WARN"
+    FAIL = "FAIL"
+    SKIP = "SKIP"
+
+
+@dataclass
+class PreflightIssue:
+    """A single issue found by a preflight check."""
+    issue_type: str
+    detail: str
+    data: dict = field(default_factory=dict)
+
+
+@dataclass
+class CheckResult:
+    """Result from a single preflight check.
+    (from 05a-preflight-checks.md, per-check result)
+    """
+    name: str
+    status: CheckStatus
+    detail: str
+    issues: list[PreflightIssue] = field(default_factory=list)
+    data: dict = field(default_factory=dict)
+
+
+@dataclass
+class PreflightResult:
+    """Aggregated result from all preflight checks.
+    (from 05a-preflight-checks.md, overall result)
+    """
+    overall: CheckStatus
+    checks: list[CheckResult] = field(default_factory=list)
+    new_decision_ids: list[str] = field(default_factory=list)
+    merge_result: dict = field(default_factory=dict)
+
+
+class PreflightError(Exception):
+    """Raised when a wxcli command fails during preflight."""
+
+
+def _run_wxcli(args: list[str]) -> list[dict]:
+    """Run a wxcli command and parse JSON output.
+    (from phase-10-preflight.md, subprocess pattern)
+    """
+    result = subprocess.run(
+        ["wxcli"] + args + ["-o", "json"],
+        capture_output=True, text=True,
+    )
+    if result.returncode != 0:
+        raise PreflightError(f"wxcli {' '.join(args)} failed: {result.stderr}")
+    stdout = result.stdout.strip()
+    if not stdout:
+        return []
+    parsed = json.loads(stdout)
+    if isinstance(parsed, list):
+        return parsed
+    if isinstance(parsed, dict):
+        return [parsed]
+    return []
+
+
+def preflight_fingerprint(*args) -> str:
+    """Compute deterministic fingerprint for preflight decisions.
+    (from 05a-preflight-checks.md, fingerprint computation)
+    """
+    canonical = json.dumps(list(args))
+    return hashlib.sha256(canonical.encode()).hexdigest()[:16]