fabric-dw 0.1.dev77__py3-none-any.whl

fabric_dw/__init__.py

@@ -0,0 +1,5 @@
+"""fabric-dw — Python CLI + MCP server for Microsoft Fabric Data Warehouse."""
+
+from fabric_dw._version import __version__
+
+__all__ = ["__version__"]

fabric_dw/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.dev77'
+__version_tuple__ = version_tuple = (0, 1, 'dev77')
+
+__commit_id__ = commit_id = None

fabric_dw/auth.py

@@ -0,0 +1,112 @@
+"""Azure credential chain with persistent token cache."""
+
+import asyncio
+import os
+from enum import StrEnum
+
+from azure.core.credentials import AccessToken, TokenCredential
+from azure.identity import (
+    ClientSecretCredential,
+    DefaultAzureCredential,
+    InteractiveBrowserCredential,
+    TokenCachePersistenceOptions,
+)
+
+from fabric_dw.exceptions import ConfigError
+
+FABRIC_SCOPE = "https://analysis.windows.net/powerbi/api/.default"
+SQL_SCOPE = "https://database.windows.net/.default"
+
+#: Shared multi-tenant Entra app for the interactive browser sign-in path.
+#: Users on any tenant can sign in without registering their own app.
+#: Override with the ``FABRIC_INTERACTIVE_CLIENT_ID`` environment variable.
+DEFAULT_INTERACTIVE_CLIENT_ID = "f666e5ee-2149-4c6a-87eb-13c9e1fdc70d"
+
+_CACHE_OPTIONS = TokenCachePersistenceOptions(name="fabric-dw", allow_unencrypted_storage=True)
+
+
+class CredentialMode(StrEnum):
+    DEFAULT = "default"
+    SERVICE_PRINCIPAL = "sp"
+    INTERACTIVE = "interactive"
+
+
+def _resolve_interactive_kwargs() -> dict[str, str]:
+    """Build keyword arguments for the interactive browser credential path.
+
+    Reads ``FABRIC_INTERACTIVE_CLIENT_ID`` (defaults to the shared app) and
+    ``FABRIC_INTERACTIVE_TENANT_ID`` (omitted when not set) from the environment.
+
+    Returns:
+        A dict with at least ``client_id`` and optionally ``tenant_id``.
+    """
+    kwargs: dict[str, str] = {
+        "client_id": os.environ.get("FABRIC_INTERACTIVE_CLIENT_ID", DEFAULT_INTERACTIVE_CLIENT_ID)
+    }
+    tenant = os.environ.get("FABRIC_INTERACTIVE_TENANT_ID")
+    if tenant:
+        kwargs["tenant_id"] = tenant
+    return kwargs
+
+
+def get_credential(mode: CredentialMode = CredentialMode.DEFAULT) -> TokenCredential:
+    """Return an Azure credential for the given mode.
+
+    Args:
+        mode: The credential mode to use. Defaults to DEFAULT.
+
+    Returns:
+        A TokenCredential appropriate for the given mode.
+
+    Raises:
+        ConfigError: If mode is SERVICE_PRINCIPAL and any of AZURE_TENANT_ID,
+            AZURE_CLIENT_ID, or AZURE_CLIENT_SECRET are missing from the environment.
+    """
+    if mode == CredentialMode.DEFAULT:
+        interactive_kwargs = _resolve_interactive_kwargs()
+        dac_kwargs: dict[str, object] = {
+            "cache_persistence_options": _CACHE_OPTIONS,
+            "exclude_interactive_browser_credential": False,
+            "interactive_browser_client_id": interactive_kwargs["client_id"],
+        }
+        if "tenant_id" in interactive_kwargs:
+            dac_kwargs["interactive_browser_tenant_id"] = interactive_kwargs["tenant_id"]
+        return DefaultAzureCredential(**dac_kwargs)
+
+    if mode == CredentialMode.SERVICE_PRINCIPAL:
+        env_vars = {
+            "AZURE_TENANT_ID": os.environ.get("AZURE_TENANT_ID"),
+            "AZURE_CLIENT_ID": os.environ.get("AZURE_CLIENT_ID"),
+            "AZURE_CLIENT_SECRET": os.environ.get("AZURE_CLIENT_SECRET"),
+        }
+        missing = [name for name, value in env_vars.items() if not value]
+        if missing:
+            raise ConfigError.missing_env_vars(missing)
+
+        return ClientSecretCredential(
+            tenant_id=env_vars["AZURE_TENANT_ID"] or "",
+            client_id=env_vars["AZURE_CLIENT_ID"] or "",
+            client_secret=env_vars["AZURE_CLIENT_SECRET"] or "",
+        )
+
+    # CredentialMode.INTERACTIVE
+    return InteractiveBrowserCredential(
+        cache_persistence_options=_CACHE_OPTIONS,
+        **_resolve_interactive_kwargs(),
+    )
+
+
+async def get_token(credential: TokenCredential, scope: str) -> AccessToken:
+    """Retrieve an access token from the credential asynchronously.
+
+    Wraps the synchronous ``credential.get_token`` call in ``asyncio.to_thread``
+    so it does not block the event loop.
+
+    Args:
+        credential: The Azure credential to use.
+        scope: The OAuth2 scope to request a token for.
+
+    Returns:
+        The raw AccessToken returned by the credential.
+    """
+    return await asyncio.to_thread(credential.get_token, scope)

fabric_dw/cache.py

@@ -0,0 +1,259 @@
+"""Persistent 24-hour filesystem name<->ID lookup cache.
+
+Stores workspace and item (Warehouse / SQLEndpoint / WarehouseSnapshot)
+name-to-UUID mappings in a single JSON file, protected by a FileLock so
+multiple concurrent CLI or MCP processes can share the cache safely.
+
+JSON shape::
+
+    {
+        "version": 1,
+        "workspaces": {
+            "<name_lower>": {"id": "<guid>", "fetched_at": "<iso8601>"}
+        },
+        "items": {
+            "<ws_uuid>": {
+                "<name_lower_or_guid_lower>": {
+                    "id": "<guid>",
+                    "kind": "<WarehouseKind>",
+                    "connection_string": "<str | null>",
+                    "fetched_at": "<iso8601>"
+                }
+            }
+        }
+    }
+
+Names are stripped of leading/trailing whitespace and lower-cased at the
+cache boundary.  GUID keys are stored lower-cased (the canonical UUID
+string form is lower-case hex with hyphens).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+import tempfile
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+import filelock
+
+from fabric_dw.models import WarehouseKind
+
+__all__ = [
+    "ItemEntry",
+    "LookupCache",
+    "WorkspaceEntry",
+]
+
+_log = logging.getLogger(__name__)
+
+_SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class WorkspaceEntry:
+    """A cached workspace name→UUID mapping."""
+
+    id: UUID
+    fetched_at: datetime
+
+
+@dataclass(frozen=True)
+class ItemEntry:
+    """A cached item (Warehouse / SQLEndpoint / Snapshot) name→detail mapping."""
+
+    id: UUID
+    kind: WarehouseKind
+    connection_string: str | None
+    fetched_at: datetime
+    display_name: str = ""
+
+
+class LookupCache:
+    """Persistent filesystem name<->UUID cache with TTL and file locking.
+
+    All name keys are normalised to lower-case at read and write time so
+    that lookups are case-insensitive.
+    """
+
+    def __init__(
+        self,
+        path: Path | None = None,
+        ttl: timedelta = timedelta(hours=24),
+    ) -> None:
+        if path is None:
+            xdg = os.environ.get("XDG_CACHE_HOME")
+            base = Path(xdg) if xdg else Path.home() / ".cache"
+            path = base / "fabric-dw" / "lookup.json"
+        self._path = path
+        self._ttl = ttl
+        self._lock = filelock.FileLock(str(path) + ".lock", timeout=5)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _empty() -> dict[str, Any]:
+        """Return a fresh empty cache skeleton (never share the same inner dicts)."""
+        return {"version": _SCHEMA_VERSION, "workspaces": {}, "items": {}}
+
+    def _read(self) -> dict[str, Any]:
+        """Read and parse the cache file; return empty skeleton on missing/corrupt."""
+        if not self._path.exists():
+            return self._empty()
+        try:
+            raw = self._path.read_text(encoding="utf-8")
+            data: dict[str, Any] = json.loads(raw)
+        except Exception:
+            _log.warning("Cache file %s is missing or corrupt; treating as empty", self._path)
+            return self._empty()
+        else:
+            if not isinstance(data, dict):
+                _log.warning("Cache file %s has unexpected shape; treating as empty", self._path)
+                return self._empty()
+            return data
+
+    def _write(self, data: dict[str, Any]) -> None:
+        """Atomically write *data* to the cache file, creating parent dirs as needed.
+
+        Uses a temp file + os.replace() so readers always see either the old or
+        the new complete file — a crash during write can never leave a truncated
+        or partially-written JSON file on disk.
+        """
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp_name = tempfile.mkstemp(
+            dir=self._path.parent,
+            prefix=".lookup_tmp_",
+            suffix=".json",
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(json.dumps(data, indent=None))
+            os.replace(tmp_name, self._path)
+        except Exception:
+            with contextlib.suppress(OSError):
+                os.unlink(tmp_name)
+            raise
+
+    def _is_fresh(self, fetched_at_str: str) -> bool:
+        """Return True when *fetched_at_str* is within the TTL window."""
+        try:
+            fetched_at = datetime.fromisoformat(fetched_at_str)
+        except (ValueError, TypeError):
+            return False
+        now = datetime.now(tz=UTC)
+        # Handle naive datetimes by assuming UTC
+        if fetched_at.tzinfo is None:
+            fetched_at = fetched_at.replace(tzinfo=UTC)
+        return (now - fetched_at) < self._ttl
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get_workspace(self, name: str) -> WorkspaceEntry | None:
+        """Return a fresh cached workspace entry or *None* on miss/expiry."""
+        with self._lock:
+            data = self._read()
+        workspaces: dict[str, Any] = data.get("workspaces", {})
+        record = workspaces.get(name.strip().lower())
+        if not isinstance(record, dict):
+            return None
+        if not self._is_fresh(record.get("fetched_at", "")):
+            return None
+        try:
+            return WorkspaceEntry(
+                id=UUID(record["id"]),
+                fetched_at=datetime.fromisoformat(record["fetched_at"]),
+            )
+        except (KeyError, ValueError, TypeError):
+            return None
+
+    def put_workspace(self, name: str, id: UUID) -> None:
+        """Store a workspace name→UUID mapping with the current timestamp."""
+        key = name.strip().lower()
+        with self._lock:
+            data = self._read()
+            workspaces: dict[str, Any] = data.setdefault("workspaces", {})
+            workspaces[key] = {
+                "id": str(id),
+                "fetched_at": datetime.now(tz=UTC).isoformat(),
+            }
+            self._write(data)
+
+    def get_item(self, workspace_id: UUID, name: str) -> ItemEntry | None:
+        """Return a fresh cached item entry or *None* on miss/expiry.
+
+        *name* may be a display name or a GUID string; both are normalised to
+        lower-case (and stripped) before lookup so the same key is found
+        regardless of how the entry was stored.
+        """
+        with self._lock:
+            data = self._read()
+        items: dict[str, Any] = data.get("items", {})
+        ws_items: dict[str, Any] = items.get(str(workspace_id), {})
+        record = ws_items.get(name.strip().lower())
+        if not isinstance(record, dict):
+            return None
+        if not self._is_fresh(record.get("fetched_at", "")):
+            return None
+        try:
+            conn = record.get("connection_string")
+            dn = record.get("display_name", "")
+            return ItemEntry(
+                id=UUID(record["id"]),
+                kind=WarehouseKind(record["kind"]),
+                connection_string=conn if isinstance(conn, str) else None,
+                fetched_at=datetime.fromisoformat(record["fetched_at"]),
+                display_name=dn if isinstance(dn, str) else "",
+            )
+        except (KeyError, ValueError, TypeError):
+            return None
+
+    def put_item(self, workspace_id: UUID, name: str, entry: ItemEntry) -> None:
+        """Store an item entry under *workspace_id* / *name*.
+
+        *name* is stripped and lower-cased.  Pass either the display name or
+        the GUID string to store an alias entry under the GUID key.
+        """
+        key = name.strip().lower()
+        with self._lock:
+            data = self._read()
+            items: dict[str, Any] = data.setdefault("items", {})
+            ws_items: dict[str, Any] = items.setdefault(str(workspace_id), {})
+            ws_items[key] = {
+                "id": str(entry.id),
+                "kind": str(entry.kind),
+                "connection_string": entry.connection_string,
+                "fetched_at": entry.fetched_at.isoformat(),
+                "display_name": entry.display_name,
+            }
+            self._write(data)
+
+    def clear(self) -> None:
+        """Erase all cached entries by writing an empty skeleton file."""
+        with self._lock:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            self._write(self._empty())
+
+    def invalidate_workspace(self, workspace_id: UUID) -> None:
+        """Remove *workspace_id* and all items cached under it."""
+        ws_id_str = str(workspace_id)
+        with self._lock:
+            data = self._read()
+            # Remove workspace entry whose id field matches
+            workspaces: dict[str, Any] = data.get("workspaces", {})
+            to_remove = [k for k, v in workspaces.items() if v.get("id") == ws_id_str]
+            for key in to_remove:
+                del workspaces[key]
+            # Drop all items under this workspace
+            items: dict[str, Any] = data.get("items", {})
+            items.pop(ws_id_str, None)
+            self._write(data)

fabric_dw/cli/__init__.py

@@ -0,0 +1,10 @@
+"""CLI entrypoint for fabric-dw."""
+
+from __future__ import annotations
+
+from fabric_dw.cli._main import cli
+
+
+def main() -> None:
+    """Entrypoint registered in pyproject.toml [project.scripts]."""
+    cli()

fabric_dw/cli/_context.py

@@ -0,0 +1,29 @@
+"""Shared CLI context dataclass passed to all commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from fabric_dw.auth import CredentialMode
+from fabric_dw.config import UserConfig, load_config
+
+
+@dataclass
+class CliContext:
+    """Carries parsed global options and lazily-constructed service clients.
+
+    Passed through Click's ``ctx.obj`` to every sub-command.
+    """
+
+    json_output: bool = False
+    yes: bool = False
+    auth: CredentialMode = field(default_factory=lambda: CredentialMode.DEFAULT)
+    verbose: bool = False
+    _config: UserConfig | None = field(default=None, repr=False, compare=False)
+
+    @property
+    def config(self) -> UserConfig:
+        """Lazily load the user config from disk on first access."""
+        if self._config is None:
+            self._config = load_config()
+        return self._config

fabric_dw/cli/_main.py

@@ -0,0 +1,82 @@
+"""Click group definition for the fabric-dw CLI."""
+
+from __future__ import annotations
+
+import logging
+
+import click
+
+from fabric_dw.auth import CredentialMode
+from fabric_dw.cli._context import CliContext
+from fabric_dw.cli.commands.audit import audit_group
+from fabric_dw.cli.commands.cache import cache_group
+from fabric_dw.cli.commands.completion import completion_group
+from fabric_dw.cli.commands.config import config_group
+from fabric_dw.cli.commands.endpoints import endpoints_group
+from fabric_dw.cli.commands.queries import queries_group
+from fabric_dw.cli.commands.snapshots import snapshots_group
+from fabric_dw.cli.commands.warehouses import warehouses_group
+from fabric_dw.cli.commands.workspaces import workspaces_group
+from fabric_dw.logging import setup_logging
+
+
+@click.group(invoke_without_command=False)
+@click.option(
+    "--json",
+    "json_output",
+    is_flag=True,
+    default=False,
+    help="Emit machine-readable JSON instead of Rich tables.",
+)
+@click.option(
+    "--auth",
+    "auth_mode",
+    type=click.Choice([m.value for m in CredentialMode], case_sensitive=False),
+    default=CredentialMode.DEFAULT.value,
+    show_default=True,
+    help="Authentication mode.",
+)
+@click.option(
+    "--yes",
+    "-y",
+    "yes",
+    is_flag=True,
+    default=False,
+    help="Skip confirmation prompts.",
+)
+@click.option(
+    "--verbose",
+    "-v",
+    "verbose",
+    is_flag=True,
+    default=False,
+    help="Enable debug logging.",
+)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    json_output: bool,
+    auth_mode: str,
+    yes: bool,
+    verbose: bool,
+) -> None:
+    """Microsoft Fabric Data Warehouse CLI."""
+    setup_logging(logging.DEBUG if verbose else logging.INFO)
+
+    ctx.obj = CliContext(
+        json_output=json_output,
+        yes=yes,
+        auth=CredentialMode(auth_mode),
+        verbose=verbose,
+    )
+
+
+cli.add_command(cache_group)
+cli.add_command(completion_group)
+cli.add_command(config_group)
+cli.add_command(workspaces_group)
+cli.add_command(warehouses_group)
+cli.add_command(endpoints_group)
+cli.add_command(audit_group)
+cli.add_command(queries_group)
+cli.add_command(snapshots_group)

fabric_dw/cli/_render.py

@@ -0,0 +1,104 @@
+"""Rich + JSON rendering helpers for CLI output."""
+
+from __future__ import annotations
+
+import json as _json
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+__all__ = [
+    "confirm",
+    "render",
+]
+
+_DEFAULT_CONSOLE = Console()
+
+
+def render(
+    data: object,
+    *,
+    json_output: bool,
+    console: Console | None = None,
+    table_title: str | None = None,
+) -> None:
+    """Print *data* to stdout using JSON or Rich formatting.
+
+    Args:
+        data: The data to render. Supported shapes:
+            - ``list[dict]`` → Rich Table (or JSON array).
+            - ``dict`` → Rich Panel (or JSON object).
+            - primitives → ``repr()`` string (or JSON scalar).
+        json_output: When *True*, emit indented JSON via ``click.echo``.
+            When *False*, use Rich for human-friendly output.
+        console: Optional Rich Console instance. When *None* the module-level
+            default console (stdout) is used. Ignored when *json_output=True*.
+        table_title: Optional title shown above the Rich Table.
+            Ignored when *json_output=True* or when *data* is not a list.
+    """
+    if json_output:
+        click.echo(_json.dumps(data, indent=2, default=str))
+        return
+
+    con = console if console is not None else _DEFAULT_CONSOLE
+
+    if isinstance(data, list):
+        _render_table(data, console=con, title=table_title)
+    elif isinstance(data, dict):
+        _render_panel(data, console=con, title=table_title)
+    else:
+        click.echo(repr(data))
+
+
+def _render_table(rows: list[object], *, console: Console, title: str | None) -> None:
+    """Render a list of dicts as a Rich Table."""
+    table = Table(title=title, show_header=True, header_style="bold")
+
+    if not rows:
+        console.print(table)
+        return
+
+    # Collect all column names in insertion order (union of all keys)
+    columns: list[str] = []
+    seen: set[str] = set()
+    for row in rows:
+        if isinstance(row, dict):
+            for key in row:
+                if key not in seen:
+                    columns.append(str(key))
+                    seen.add(key)
+
+    for col in columns:
+        table.add_column(col)
+
+    for row in rows:
+        if isinstance(row, dict):
+            table.add_row(*[str(row.get(col, "")) for col in columns])
+        else:
+            table.add_row(str(row))
+
+    console.print(table)
+
+
+def _render_panel(data: dict[str, object], *, console: Console, title: str | None) -> None:
+    """Render a single dict as a Rich Panel with key: value lines."""
+    lines = "\n".join(f"[bold]{k}[/bold]: {v}" for k, v in data.items())
+    panel = Panel(lines, title=title)
+    console.print(panel)
+
+
+def confirm(message: str, *, yes: bool) -> bool:
+    """Ask the user for confirmation, skipping the prompt when *yes=True*.
+
+    Args:
+        message: The confirmation message shown to the user.
+        yes: When *True*, return ``True`` immediately without prompting.
+
+    Returns:
+        ``True`` if the action should proceed, ``False`` otherwise.
+    """
+    if yes:
+        return True
+    return click.confirm(message, default=False)