teamspend-cli 0.2.1__py3-none-any.whl

teamspend/cli.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""
+teamspend CLI.
+
+Ported from src/cli.ts (which uses Node's built-in `parseArgs`); this port
+uses the stdlib `argparse` to avoid a CLI-framework dependency. Flags,
+defaults, and validation error text are kept identical to the npm CLI's.
+
+Console entry point: `teamspend --tools <a>,<b> --before ... --after ...`,
+installed via the `teamspend` console-script defined in pyproject.toml.
+"""
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import os
+import re
+import sys
+from typing import List, Optional, Tuple
+
+from .adapters.claude_code import fetch_claude_code_spend
+from .adapters.claude_code_personal import fetch_claude_code_personal_usage
+from .adapters.codex import fetch_codex_usage
+from .adapters.copilot import fetch_copilot_spend
+from .adapters.csv_import import import_from_csv
+from .adapters.cursor import fetch_cursor_spend
+from .adapters.opencode import fetch_opencode_spend
+from .compare import ComparisonReport, PeriodOutcome, build_comparison
+from .errors import DataUnavailableError, InvalidCliArgError
+from .output import render_terminal_summary, scaffold_gitignore, write_json_report
+from .types import AdapterResult, BreakdownMode, DateWindow, ToolId
+
+KNOWN_TOOLS: List[ToolId] = [
+    "cursor",
+    "claude-code",
+    "copilot",
+    "opencode",
+    "claude-code-personal",
+    "codex",
+]
+KNOWN_BREAKDOWN_MODES: List[BreakdownMode] = ["session"]
+DATE_RANGE_RE = re.compile(r"^(\d{4}-\d{2}-\d{2}):(\d{4}-\d{2}-\d{2})$")
+_VERSION = "0.1.0"
+
+
+def _parse_date_range(flag: str, value: str) -> DateWindow:
+    match = DATE_RANGE_RE.match(value)
+    if not match:
+        raise InvalidCliArgError(
+            f'--{flag} must be in the form YYYY-MM-DD:YYYY-MM-DD, got "{value}"'
+        )
+    return DateWindow(start=match.group(1), end=match.group(2))
+
+
+def _validate_tools(raw_tools: str) -> Tuple[ToolId, ToolId]:
+    parts = [t.strip() for t in raw_tools.split(",")]
+    if len(parts) != 2:
+        raise InvalidCliArgError(
+            f'--tools must name exactly two tools, got "{raw_tools}"'
+        )
+    for tool in parts:
+        if tool not in KNOWN_TOOLS:
+            raise InvalidCliArgError(
+                f'Unknown tool "{tool}" -- expected one of: {", ".join(KNOWN_TOOLS)}'
+            )
+    return parts[0], parts[1]  # type: ignore[return-value]
+
+
+def _validate_window_order(before: DateWindow, after: DateWindow) -> None:
+    if before.start >= after.start:
+        raise InvalidCliArgError(
+            f"--before ({before.start}) must be earlier than --after ({after.start})"
+        )
+
+
+def _parse_breakdown_mode(raw: Optional[str]) -> Optional[BreakdownMode]:
+    """
+    Parses --breakdown. Unset (None) is the default (no change from prior
+    behavior). A set-but-unrecognized value raises rather than silently
+    being ignored, since a typo like `--breakdown sessions` should surface
+    immediately instead of quietly reporting the plain flat total the
+    caller didn't ask for.
+    """
+    if raw is None:
+        return None
+    if raw in KNOWN_BREAKDOWN_MODES:
+        return raw  # type: ignore[return-value]
+    raise InvalidCliArgError(
+        f'--breakdown must be one of: {", ".join(KNOWN_BREAKDOWN_MODES)}, got "{raw}"'
+    )
+
+
+def _strip_sessions_unless_requested(
+    result: Optional[AdapterResult], breakdown: Optional[BreakdownMode]
+) -> Optional[AdapterResult]:
+    """
+    Removes per-session data from a fetched result when the caller didn't
+    ask for it via --breakdown session. Adapters populate `sessions`
+    whenever their underlying data has it, independent of any CLI flag;
+    stripping it back out here (rather than teaching every adapter about
+    the flag) is what keeps the default JSON report and terminal output
+    unchanged from before this feature existed.
+    """
+    if result is None or breakdown == "session":
+        return result
+    for user in result.users:
+        user.sessions = None
+    return result
+
+
+def _parse_copilot_seat_price() -> Optional[float]:
+    """
+    Parses TEAMSPEND_COPILOT_SEAT_PRICE_USD, an optional per-seat monthly
+    price the caller supplies since GitHub's API never exposes an org's
+    actual negotiated seat price. Returns None if unset. Raises
+    InvalidCliArgError for a set-but-unparseable or negative value.
+    """
+    raw = os.environ.get("TEAMSPEND_COPILOT_SEAT_PRICE_USD")
+    if not raw:
+        return None
+    try:
+        parsed = float(raw)
+    except ValueError:
+        parsed = float("nan")
+    if not (parsed >= 0):
+        raise InvalidCliArgError(
+            f'TEAMSPEND_COPILOT_SEAT_PRICE_USD must be a non-negative number, got "{raw}"'
+        )
+    return parsed
+
+
+def _fetch_tool(
+    tool: ToolId, window: DateWindow, csv_path: Optional[str]
+) -> Optional[AdapterResult]:
+    env_var = f"TEAMSPEND_{tool.upper().replace('-', '_')}_TOKEN"
+    api_key = os.environ.get(env_var)
+
+    try:
+        if tool == "cursor":
+            if not api_key:
+                raise RuntimeError(f"Missing {env_var}")
+            return fetch_cursor_spend(window, api_key)
+        if tool == "claude-code":
+            if not api_key:
+                raise RuntimeError(f"Missing {env_var}")
+            return fetch_claude_code_spend(window, api_key)
+        if tool == "copilot":
+            if not api_key:
+                raise RuntimeError(f"Missing {env_var}")
+            org = os.environ.get("TEAMSPEND_COPILOT_ORG")
+            if not org:
+                raise RuntimeError("Missing TEAMSPEND_COPILOT_ORG")
+            return fetch_copilot_spend(
+                window, api_key, org, _parse_copilot_seat_price()
+            )
+        if tool == "opencode":
+            # No API key: opencode has no admin/team API, only local
+            # per-machine session logs (see adapters/opencode.py for how
+            # those are resolved and read).
+            return fetch_opencode_spend(window)
+        if tool == "claude-code-personal":
+            # Deliberately no credential check -- this mode reads Claude
+            # Code's own local JSONL session logs and never calls an admin
+            # API, so TEAMSPEND_CLAUDE_CODE_PERSONAL_TOKEN is never
+            # required.
+            return fetch_claude_code_personal_usage(window)
+        if tool == "codex":
+            # No API key: Codex CLI has no admin/team API, only local
+            # per-machine rollout logs (see adapters/codex.py for how
+            # those are resolved and read).
+            return fetch_codex_usage(window)
+        raise InvalidCliArgError(f'No adapter for tool "{tool}"')
+    except DataUnavailableError:
+        if csv_path:
+            return import_from_csv(csv_path, tool, window)
+        raise
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="teamspend",
+        add_help=False,
+        description=(
+            "Compare AI coding tool spend before and after a migration."
+        ),
+    )
+    parser.add_argument("--tools")
+    parser.add_argument("--before")
+    parser.add_argument("--after")
+    parser.add_argument("--json", action="store_true", default=False)
+    parser.add_argument("--before-csv", dest="before_csv")
+    parser.add_argument("--after-csv", dest="after_csv")
+    parser.add_argument("--breakdown")
+    parser.add_argument("--version", action="store_true", default=False)
+    parser.add_argument("-h", "--help", action="store_true", default=False)
+    return parser
+
+
+_USAGE = (
+    "Usage: teamspend --tools <a>,<b> --before YYYY-MM-DD:YYYY-MM-DD "
+    "--after YYYY-MM-DD:YYYY-MM-DD [--json] [--before-csv <path>] [--after-csv <path>] "
+    "[--breakdown session]"
+)
+
+
+def run(argv: List[str]) -> int:
+    """
+    Runs the CLI against `argv` (NOT including the program name -- this
+    matches Python's usual `sys.argv[1:]` convention, unlike the TypeScript
+    original's `process.argv.slice(2)` call site which strips two leading
+    entries; both end up passing "just the flags" to their respective
+    `run`/`run_cli` functions). Returns the process exit code.
+    """
+    parser = _build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit:
+        return 1
+
+    if args.help:
+        print(_USAGE)
+        return 0
+
+    if args.version:
+        print(f"teamspend {_VERSION}")
+        return 0
+
+    try:
+        if not args.tools or not args.before or not args.after:
+            print(_USAGE, file=sys.stderr)
+            return 1
+
+        before_tool, after_tool = _validate_tools(args.tools)
+        before_window = _parse_date_range("before", args.before)
+        after_window = _parse_date_range("after", args.after)
+        _validate_window_order(before_window, after_window)
+        breakdown = _parse_breakdown_mode(args.breakdown)
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=2) as executor:
+            before_future = executor.submit(
+                _fetch_tool, before_tool, before_window, args.before_csv
+            )
+            after_future = executor.submit(
+                _fetch_tool, after_tool, after_window, args.after_csv
+            )
+
+            before_result: Optional[AdapterResult] = None
+            before_error: Optional[BaseException] = None
+            try:
+                before_result = before_future.result()
+            except BaseException as error:  # noqa: BLE001 -- mirrors Promise.allSettled, any adapter failure becomes a per-side error, never a crash
+                before_error = error
+
+            after_result: Optional[AdapterResult] = None
+            after_error: Optional[BaseException] = None
+            try:
+                after_result = after_future.result()
+            except BaseException as error:  # noqa: BLE001
+                after_error = error
+
+        before = PeriodOutcome(
+            label="before",
+            tool=before_tool,
+            result=_strip_sessions_unless_requested(before_result, breakdown),
+            error=before_error,
+        )
+        after = PeriodOutcome(
+            label="after",
+            tool=after_tool,
+            result=_strip_sessions_unless_requested(after_result, breakdown),
+            error=after_error,
+        )
+
+        report: ComparisonReport = build_comparison(before, after)
+        cwd = os.getcwd()
+        scaffolded = scaffold_gitignore(cwd)
+        json_path = write_json_report(report, cwd)
+
+        if scaffolded:
+            print(
+                "Note: teamspend-snapshot-*.json contains per-user email and "
+                "spend data -- added to .gitignore.",
+                file=sys.stderr,
+            )
+
+        # Printed every run, not just on first-run gitignore scaffolding: a
+        # .gitignore entry protects the on-disk file, but does nothing about
+        # this same per-user email + spend data being printed to stdout,
+        # which lands in CI build logs (often world-readable for public
+        # repos) if this command is wired into a scheduled workflow.
+        print(
+            "Note: this output includes per-user email and spend data. If "
+            "running in CI, confirm build logs are private.",
+            file=sys.stderr,
+        )
+
+        if args.json:
+            import json as json_module
+
+            from .output import report_to_json_dict
+
+            print(json_module.dumps(report_to_json_dict(report), indent=2))
+        else:
+            print(render_terminal_summary(report, breakdown))
+            print(f"\nFull report: {json_path}")
+
+        return 0 if before.result and after.result else 1
+    except Exception as error:  # noqa: BLE001 -- top-level crash guard, mirrors src/cli.ts's catch-all
+        print(str(error), file=sys.stderr)
+        return 1
+
+
+def main() -> None:
+    sys.exit(run(sys.argv[1:]))
+
+
+if __name__ == "__main__":
+    main()

teamspend/compare.py

@@ -0,0 +1,77 @@
+"""
+Builds the before/after comparison report from two independently-resolved
+adapter fetches.
+
+Ported from src/compare.ts. Never treats a partial failure as a complete
+comparison: if either side failed, delta is null and the failed side is
+marked, not silently dropped from the report.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Literal, Optional
+
+from .types import AdapterResult, ToolId, top_spenders
+
+PeriodLabel = Literal["before", "after"]
+
+
+@dataclass
+class PeriodOutcome:
+    label: PeriodLabel
+    tool: ToolId
+    result: Optional[AdapterResult]
+    error: Optional[BaseException]
+
+
+@dataclass
+class TopSpenderEntry:
+    period: PeriodLabel
+    user_email: Optional[str]
+    cost_usd: float
+
+
+@dataclass
+class ComparisonReport:
+    before: PeriodOutcome
+    after: PeriodOutcome
+    delta_usd: Optional[float]
+    delta_percent: Optional[float]
+    top_spenders_across_both: List[TopSpenderEntry] = field(default_factory=list)
+
+
+def build_comparison(before: PeriodOutcome, after: PeriodOutcome) -> ComparisonReport:
+    before_cost = before.result.total_cost_usd if before.result else None
+    after_cost = after.result.total_cost_usd if after.result else None
+
+    delta_usd = (
+        after_cost - before_cost
+        if before_cost is not None and after_cost is not None
+        else None
+    )
+    delta_percent = (
+        (delta_usd / before_cost) * 100
+        if delta_usd is not None and before_cost is not None and before_cost != 0
+        else None
+    )
+
+    top_spenders_across_both: List[TopSpenderEntry] = []
+    if before.result:
+        for user in top_spenders(before.result.users, 5):
+            top_spenders_across_both.append(
+                TopSpenderEntry("before", user.user_email, user.cost_usd)
+            )
+    if after.result:
+        for user in top_spenders(after.result.users, 5):
+            top_spenders_across_both.append(
+                TopSpenderEntry("after", user.user_email, user.cost_usd)
+            )
+    top_spenders_across_both.sort(key=lambda entry: entry.cost_usd, reverse=True)
+
+    return ComparisonReport(
+        before=before,
+        after=after,
+        delta_usd=delta_usd,
+        delta_percent=delta_percent,
+        top_spenders_across_both=top_spenders_across_both[:5],
+    )

teamspend/errors.py

@@ -0,0 +1,96 @@
+"""
+Named error types for every failure mode the fetch/compare pipeline can hit.
+
+Ported from src/errors.ts. Message text is kept identical to the
+TypeScript original so a bug report reads the same regardless of which
+distribution (npm or PyPI) produced it.
+"""
+from __future__ import annotations
+
+from typing import Iterable, List, Sequence
+
+
+class AuthenticationError(Exception):
+    """Raised when an admin API responds 401/403 for a tool's credential."""
+
+    def __init__(self, tool: str, credential_env_var: str) -> None:
+        self.tool = tool
+        self.credential_env_var = credential_env_var
+        super().__init__(
+            f"Auth failed for {tool}: check {credential_env_var} is set and valid"
+        )
+
+
+class RetryExhaustedError(Exception):
+    """Raised when fetch_with_retry exhausts its retry budget."""
+
+    def __init__(self, tool: str, failure_kind: str, attempts: int) -> None:
+        self.tool = tool
+        self.failure_kind = failure_kind
+        self.attempts = attempts
+        super().__init__(f"{tool} failed after {attempts} retries ({failure_kind})")
+
+
+class SchemaDriftError(Exception):
+    """Raised when a vendor API response is missing a field require_field expects."""
+
+    def __init__(
+        self,
+        tool: str,
+        unexpected_field: str,
+        tried_aliases: Sequence[str] = (),
+    ) -> None:
+        self.tool = tool
+        self.unexpected_field = unexpected_field
+        self.tried_aliases: List[str] = list(tried_aliases)
+        alias_suffix = (
+            f" (also checked known aliases: {', '.join(self.tried_aliases)})"
+            if self.tried_aliases
+            else ""
+        )
+        super().__init__(
+            f"{tool} API returned an unexpected shape (field: {unexpected_field})"
+            f"{alias_suffix}, teamspend may need an update"
+        )
+
+
+class DataUnavailableError(Exception):
+    """Raised when a tool's admin API cannot serve the requested window at all."""
+
+    def __init__(self, tool: str, reason: str) -> None:
+        self.tool = tool
+        self.reason = reason
+        super().__init__(
+            f"No API data available for {tool}: {reason}, "
+            "provide a CSV file per the documented schema"
+        )
+
+
+class CSVSchemaError(Exception):
+    """Raised when an imported CSV is missing one of the required columns."""
+
+    def __init__(self, expected_columns: Iterable[str]) -> None:
+        self.expected_columns: List[str] = list(expected_columns)
+        super().__init__(
+            f"CSV file doesn't match expected columns: {', '.join(self.expected_columns)}"
+        )
+
+
+class EmptyCSVError(Exception):
+    """Raised for a zero-byte or whitespace-only CSV file."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        super().__init__(f"CSV file is empty: {path}")
+
+
+class CSVRowError(Exception):
+    """Raised for a single malformed CSV row (bad cost, empty email)."""
+
+    def __init__(self, row_number: int, reason: str) -> None:
+        self.row_number = row_number
+        super().__init__(f"CSV row {row_number} is invalid: {reason}")
+
+
+class InvalidCliArgError(Exception):
+    """Raised for a malformed or missing CLI flag."""

teamspend/http_client.py

@@ -0,0 +1,204 @@
+"""
+Shared fetch+retry wrapper used by every admin-API adapter.
+
+Ported from src/http-client.ts. Retries 429 and 5xx/timeout identically
+with exponential backoff (base 0.5s, doubling, cap 3 retries), then fails
+with a named error rather than ever returning a partial or guessed result.
+
+Uses only `urllib` from the standard library (no `requests` dependency),
+matching the npm package's "zero runtime dependencies" design -- the
+TypeScript original uses native `fetch` for the same reason.
+
+The real network call is a separate, injectable `transport` parameter so
+tests can simulate arbitrary HTTP statuses and network failures without a
+real socket, the same technique the TypeScript test suite uses by stubbing
+the global `fetch`.
+"""
+from __future__ import annotations
+
+import json as json_module
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional, Sequence
+from urllib.parse import urlsplit
+
+from .errors import AuthenticationError, RetryExhaustedError, SchemaDriftError
+
+MAX_RETRIES = 3
+BASE_DELAY_SECONDS = 0.5
+REQUEST_TIMEOUT_SECONDS = 30.0
+
+_SENSITIVE_HEADERS = ("Authorization", "x-api-key")
+
+
+class _SameOriginRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Strips auth headers before following a redirect to a different host.
+
+    urllib's default HTTPRedirectHandler forwards every original request
+    header -- including Authorization/x-api-key -- to wherever a 3xx
+    Location points, even a different host. `requests` strips auth headers
+    on cross-origin redirects by default; bare urllib does not. Every
+    teamspend admin-API call carries a live vendor token, so a compromised
+    or misconfigured upstream (or a MITM in front of it) could otherwise
+    use a redirect to exfiltrate the token to an attacker-controlled host.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        new_request = super().redirect_request(req, fp, code, msg, headers, newurl)
+        if new_request is None:
+            return None
+        if urlsplit(req.full_url).netloc != urlsplit(newurl).netloc:
+            for header in _SENSITIVE_HEADERS:
+                # Request.remove_header() does a raw dict .pop() with no case
+                # normalization, while add_header() stores keys via
+                # .capitalize() ("x-api-key" -> "X-api-key"). Passing the raw
+                # header name here silently no-ops for anything whose casing
+                # doesn't already match its capitalize()'d form.
+                new_request.remove_header(header.capitalize())
+        return new_request
+
+
+_opener = urllib.request.build_opener(_SameOriginRedirectHandler)
+
+
+@dataclass
+class HttpResponse:
+    status: int
+    body: bytes
+
+    def json(self) -> Any:
+        return json_module.loads(self.body.decode("utf-8"))
+
+
+class TransportError(Exception):
+    """Internal: network-level failure (timeout, DNS, connection refused).
+
+    Never raised to a caller of fetch_with_retry -- always converted into a
+    RetryExhaustedError("timeout") once retries are exhausted, matching the
+    TypeScript original's handling of a rejected fetch() promise.
+    """
+
+
+Transport = Callable[[str, Dict[str, str], float], HttpResponse]
+
+
+def default_transport(url: str, headers: Dict[str, str], timeout: float) -> HttpResponse:
+    """Real network transport. GET only -- every teamspend admin-API call is a GET."""
+    request = urllib.request.Request(url, headers=headers, method="GET")
+    try:
+        with _opener.open(request, timeout=timeout) as response:  # noqa: S310 -- fixed https:// admin-API URLs built from constants, never from unsanitized input
+            return HttpResponse(status=response.status, body=response.read())
+    except urllib.error.HTTPError as error:
+        # HTTPError already carries the response body/status for non-2xx --
+        # treat it as a normal (non-2xx) HttpResponse so the retry/auth
+        # logic below can inspect the status code uniformly.
+        return HttpResponse(status=error.code, body=error.read())
+    except (urllib.error.URLError, TimeoutError, OSError) as error:
+        raise TransportError(str(error)) from error
+
+
+def _is_retryable(status: int) -> Optional[str]:
+    if status == 429:
+        return "rate-limit"
+    if 500 <= status < 600:
+        return "server-error"
+    return None
+
+
+def fetch_with_retry(
+    tool: str,
+    url: str,
+    auth_header: Dict[str, str],
+    *,
+    transport: Optional[Transport] = None,
+    sleep: Callable[[float], None] = time.sleep,
+    response_type: str = "json",
+    empty_on: Sequence[int] = (),
+) -> Any:
+    """
+    Fetches `url` with `auth_header`, retrying 429/5xx/timeout up to
+    MAX_RETRIES times with exponential backoff. Returns the parsed JSON
+    body on success (or the raw text body if `response_type="text"` --
+    used by the Copilot adapter for its NDJSON report downloads, which
+    aren't valid single-document JSON). Raises AuthenticationError
+    immediately on 401/403 (never retried), RetryExhaustedError once the
+    retry budget is spent.
+
+    `empty_on` is a set of status codes that resolve to `None` instead of
+    raising -- used by the Copilot adapter to treat a 404 on a single day's
+    report (no activity that day) as "zero data," not a failure. Never
+    passed by Cursor/Claude Code, which have no such concept.
+
+    `transport` defaults to None and resolves to `default_transport` inside
+    the function body (rather than as the parameter's default value) on
+    purpose: a default value is bound once, at function-definition time, so
+    binding it directly to `default_transport` would freeze a stale
+    reference that a test monkeypatching `http_client.default_transport`
+    could never actually intercept.
+    """
+    if transport is None:
+        transport = default_transport
+    last_failure_kind = "timeout"
+
+    for attempt in range(MAX_RETRIES + 1):
+        try:
+            response = transport(url, auth_header, REQUEST_TIMEOUT_SECONDS)
+        except TransportError:
+            last_failure_kind = "timeout"
+            if attempt < MAX_RETRIES:
+                sleep(BASE_DELAY_SECONDS * (2**attempt))
+                continue
+            raise RetryExhaustedError(tool, last_failure_kind, attempt + 1)
+
+        if response.status in (401, 403):
+            raise AuthenticationError(
+                tool, f"TEAMSPEND_{tool.upper().replace('-', '_')}_TOKEN"
+            )
+
+        if response.status in empty_on:
+            return None
+
+        retry_kind = _is_retryable(response.status)
+        if retry_kind:
+            last_failure_kind = retry_kind
+            if attempt < MAX_RETRIES:
+                sleep(BASE_DELAY_SECONDS * (2**attempt))
+                continue
+            raise RetryExhaustedError(tool, retry_kind, attempt + 1)
+
+        if not (200 <= response.status < 300):
+            raise RuntimeError(f"{tool} returned unexpected status {response.status}")
+
+        if response_type == "text":
+            return response.body.decode("utf-8")
+        return response.json()
+
+    # Unreachable, but keeps type checkers satisfied about a return path.
+    raise RetryExhaustedError(tool, last_failure_kind, MAX_RETRIES + 1)
+
+
+def require_field(
+    obj: Dict[str, Any],
+    field_name: str,
+    tool: str,
+    aliases: Sequence[str] = (),
+) -> Any:
+    """
+    Asserts a field exists on a parsed API response before it is read.
+    Raises SchemaDriftError rather than silently coercing/guessing when a
+    vendor's response shape changes without notice.
+
+    `aliases` is an optional, ordered list of legacy/alternate key names to
+    fall back to if the primary `field_name` is absent, guarding against a
+    vendor silently renaming a field. No adapter currently passes aliases --
+    Cursor and Anthropic have not renamed anything -- but the mechanism
+    exists so a future rename degrades gracefully instead of hard-failing.
+    """
+    if field_name in obj and obj[field_name] is not None:
+        return obj[field_name]
+    for alias in aliases:
+        if alias in obj and obj[alias] is not None:
+            return obj[alias]
+    raise SchemaDriftError(tool, field_name, list(aliases))