pbi-enterprise-cli 0.1.0.dev0__py3-none-any.whl

pbi_cli/cli.py

@@ -0,0 +1,332 @@
+"""Main CLI entry point for pbi-cli."""
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from pbi_cli import __version__
+from pbi_cli.commands import (
+    calendar_cmd,
+    connections,
+    custom_visual,
+    database,
+    dax,
+    deploy,
+    docs,
+    filter_cmd,
+    govern,
+    layout,
+    measure,
+    model,
+    partition,
+    repl,
+    report,
+    security,
+    server_cmd,
+    skills_cmd,
+    source,
+    theme,
+    trace,
+    visual,
+    watch,
+)
+
+console = Console()
+
+
+def _apply_dry_run(ctx: click.Context, param: click.Parameter, value: bool) -> bool:
+    ctx.ensure_object(dict)
+    ctx.obj["dry_run"] = value
+    return value
+
+
+@click.group()
+@click.version_option(__version__, prog_name="pbi")
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    is_eager=True,
+    expose_value=False,
+    callback=_apply_dry_run,
+    help="Show what would change without applying any writes.",
+)
+@click.option(
+    "--json",
+    "output_json",
+    is_flag=True,
+    help="Output results as JSON.",
+)
+@click.option(
+    "--backend",
+    type=click.Choice(["desktop", "xmla", "mock"]),
+    default="desktop",
+    show_default=True,
+    help="Backend to use for Power BI connection.",
+)
+@click.option(
+    "--port",
+    type=int,
+    default=None,
+    help="Override the local Analysis Services port (desktop backend).",
+)
+@click.pass_context
+def cli(ctx: click.Context, output_json: bool, backend: str, port: int | None) -> None:
+    """pbi — Power BI one-stop-shop CLI for AI-driven development.
+
+    Connect, model, visualize, govern, test, and deploy Power BI solutions
+    from the command line. Designed for use with Claude Code.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj.setdefault("dry_run", False)
+    ctx.obj["output_json"] = output_json
+    ctx.obj["backend"] = backend
+    if port:
+        ctx.obj["port"] = port
+
+
+# Register command groups
+cli.add_command(source.source)
+cli.add_command(measure.measure)
+cli.add_command(model.model)
+cli.add_command(dax.dax)
+cli.add_command(report.report)
+cli.add_command(visual.visual)
+cli.add_command(layout.layout)
+cli.add_command(theme.theme)
+cli.add_command(govern.govern)
+cli.add_command(deploy.deploy)
+cli.add_command(docs.docs)
+cli.add_command(database.database)
+cli.add_command(server_cmd.server)
+cli.add_command(watch.watch)
+cli.add_command(security.security)
+cli.add_command(partition.partition)
+cli.add_command(filter_cmd.filter_cmd)
+cli.add_command(trace.trace)
+cli.add_command(trace.benchmark)
+cli.add_command(connections.connections)
+cli.add_command(skills_cmd.skills_cmd)
+cli.add_command(calendar_cmd.calendar_cmd)
+cli.add_command(calendar_cmd.culture_cmd)
+cli.add_command(repl.repl)
+cli.add_command(custom_visual.custom_visual)
+
+
+@cli.command()
+@click.option("--port", type=int, default=None, help="Explicit port (auto-detected if omitted).")
+@click.pass_context
+def connect(ctx: click.Context, port: int | None) -> None:
+    """Connect to the running Power BI Desktop instance and show model info."""
+    from pbi_cli.backends.tom_backend import TomBackend, find_pbi_port
+
+    detected = port or find_pbi_port()
+    if not detected:
+        console.print("[red]No running Power BI Desktop found.[/red]")
+        console.print("Open a PBIX file in Power BI Desktop and try again.")
+        raise SystemExit(1)
+    console.print(f"[cyan]Connecting to localhost:{detected}...[/cyan]")
+    b = TomBackend()
+    b.connect(port=detected)
+    info = b.model_info()
+    console.print(
+        f"[green]Connected![/green] Model: [bold]{info['name']}[/bold]  (CompatibilityLevel {info['compatibilityLevel']})"  # noqa: E501
+    )
+    tables = b.table_list()
+    console.print(f"Tables: {', '.join(t['name'] for t in tables)}")
+    b.disconnect()
+
+
+@cli.command()
+@click.pass_context
+def doctor(ctx: click.Context) -> None:
+    """Diagnose setup issues: pythonnet, DLL compatibility, XMLA connectivity."""
+    from pbi_cli.commands._doctor import run_doctor
+
+    run_doctor(ctx.obj.get("output_json", False))
+
+
+@cli.command()
+@click.option("--yes", is_flag=True, help="Skip confirmation prompt.")
+@click.pass_context
+def undo(ctx: click.Context, yes: bool) -> None:
+    """Revert the last write command using the auto-snapshot."""
+    from pbi_cli._snapshot import latest_snapshot, restore_snapshot
+
+    snapshot = latest_snapshot()
+    if not snapshot:
+        console.print("[yellow]No snapshots found. Nothing to undo.[/yellow]")
+        console.print("Snapshots are created automatically before each write operation.")
+        return
+
+    console.print(f"[cyan]Latest snapshot:[/cyan] {snapshot.name}")
+    if not yes:
+        click.confirm(
+            "Restore this snapshot? This will overwrite current measure state.", abort=True
+        )
+
+    from pbi_cli.backends.tom_backend import TomBackend, find_pbi_port
+
+    port = find_pbi_port()
+    if not port:
+        console.print("[red]No running Power BI Desktop found.[/red]")
+        raise SystemExit(1)
+    b = TomBackend()
+    b.connect(port=port)
+    restored = restore_snapshot(snapshot, b)
+    b.disconnect()
+
+    from pbi_cli._audit import write_audit_entry
+
+    write_audit_entry("undo", extra={"snapshot": snapshot.name, "restored": restored})
+    console.print(
+        f"[green]Restored:[/green] {restored['measures_restored']} measures from snapshot {snapshot.name}"  # noqa: E501
+    )
+
+
+@cli.command("skill-validate")
+@click.argument("skill_path", type=click.Path(exists=True))
+@click.pass_context
+def skill_validate(ctx: click.Context, skill_path: str) -> None:
+    """Lint a SKILL.md file: validate frontmatter fields, description triggers, and structure (F4)."""  # noqa: E501
+    import re
+    from pathlib import Path
+
+    path = Path(skill_path)
+    if path.is_dir():
+        skill_file = path / "SKILL.md"
+    else:
+        skill_file = path
+
+    if not skill_file.exists():
+        console.print(f"[red]SKILL.md not found:[/red] {skill_file}")
+        raise SystemExit(1)
+
+    content = skill_file.read_text(encoding="utf-8")
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    # Extract frontmatter
+    fm_match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+    if not fm_match:
+        errors.append("Missing YAML frontmatter block (--- ... ---)")
+        _report_validation(skill_file, errors, warnings, ctx)
+        return
+
+    fm_text = fm_match.group(1)
+
+    # Required frontmatter fields
+    required_fields = ["name", "description", "version", "requires"]
+    for field in required_fields:
+        if not re.search(rf"^{field}:", fm_text, re.MULTILINE):
+            errors.append(f"Missing required frontmatter field: '{field}'")
+
+    # Description must contain action triggers (Use when / triggers on)
+    if re.search(r"^description:", fm_text, re.MULTILINE):
+        desc_block = re.search(r"^description:(.+?)(?=^\w|\Z)", fm_text, re.DOTALL | re.MULTILINE)
+        if desc_block:
+            desc_text = desc_block.group(1)
+            if not re.search(
+                r"(Use when|triggers on|trigger|when the user)", desc_text, re.IGNORECASE
+            ):
+                warnings.append(
+                    "description should include trigger phrases like 'Use when' or 'triggers on'"
+                )
+            if not re.search(r"Do NOT", desc_text, re.IGNORECASE):
+                warnings.append("description should include a 'Do NOT trigger' exclusion clause")
+
+    # Body must have at least one code block
+    body = content[fm_match.end() :]
+    if "```" not in body:
+        warnings.append("No code blocks found — SKILL.md should include command examples")
+
+    # Must have a Quick Reference or Commands section
+    if not re.search(r"^#{1,3}\s+(Quick Reference|Commands|Usage)", body, re.MULTILINE):
+        warnings.append("No 'Quick Reference' or 'Commands' section found")
+
+    _report_validation(skill_file, errors, warnings, ctx)
+
+
+def _report_validation(
+    skill_file: "Path", errors: list, warnings: list, ctx: "click.Context"
+) -> None:
+    console.print(f"[bold]Validating:[/bold] {skill_file}")
+    if not errors and not warnings:
+        console.print("[green]OK SKILL.md is valid.[/green]")
+        return
+    for e in errors:
+        console.print(f"  [red][ERROR][/red] {e}")
+    for w in warnings:
+        console.print(f"  [yellow][WARN][/yellow]  {w}")
+    if errors:
+        raise SystemExit(1)
+
+
+@cli.command()
+@click.option(
+    "--shell",
+    type=click.Choice(["bash", "zsh", "fish", "powershell"]),
+    default=None,
+    help="Shell to generate completions for (auto-detected if omitted).",
+)
+def completions(shell: str | None) -> None:
+    """Print shell completion setup instructions or generate the completion script (F6).
+
+    \b
+    Bash:        source <(pbi completions --shell bash)
+    Zsh:         pbi completions --shell zsh > ~/.zfunc/_pbi && autoload -U compinit && compinit
+    Fish:        pbi completions --shell fish > ~/.config/fish/completions/pbi.fish
+    PowerShell:  pbi completions --shell powershell | Out-String | Invoke-Expression
+    """
+    import os
+    import subprocess
+
+    detected = shell or _detect_shell()
+    env_var = f"_{cli.name.upper().replace('-', '_')}_COMPLETE"  # type: ignore[union-attr]
+
+    env = {**os.environ, env_var: f"{detected}_source"}
+    try:
+        result = subprocess.run(
+            ["pbi"],
+            env=env,
+            capture_output=True,
+            text=True,
+        )
+        if result.stdout:
+            click.echo(result.stdout, nl=False)
+        else:
+            _print_completion_instructions(detected)
+    except Exception:
+        _print_completion_instructions(detected)
+
+
+def _detect_shell() -> str:
+    import os
+
+    shell_env = os.environ.get("SHELL", "")
+    if "zsh" in shell_env:
+        return "zsh"
+    if "fish" in shell_env:
+        return "fish"
+    if os.name == "nt":
+        return "powershell"
+    return "bash"
+
+
+def _print_completion_instructions(shell: str) -> None:
+    instructions = {
+        "bash": ('# Add to ~/.bashrc:\neval "$(_PBI_COMPLETE=bash_source pbi)"'),
+        "zsh": ('# Add to ~/.zshrc:\neval "$(_PBI_COMPLETE=zsh_source pbi)"'),
+        "fish": (
+            "# Save to ~/.config/fish/completions/pbi.fish:\n_PBI_COMPLETE=fish_source pbi | source"
+        ),
+        "powershell": (
+            "# Add to your PowerShell profile:\n"
+            '$env:_PBI_COMPLETE = "powershell_source"; pbi | Out-String | Invoke-Expression'
+        ),
+    }
+    console.print(instructions.get(shell, f"Shell '{shell}' not recognised."))
+
+
+if __name__ == "__main__":
+    cli()

pbi_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command groups for pbi-cli."""

pbi_cli/commands/_doctor.py

@@ -0,0 +1,84 @@
+"""pbi doctor — diagnose setup issues."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def run_doctor(output_json: bool) -> None:
+    checks = []
+
+    # Python version
+    checks.append(
+        {
+            "check": "Python version",
+            "status": "pass" if sys.version_info >= (3, 10) else "fail",
+            "detail": f"{sys.version}",
+        }
+    )
+
+    # pythonnet
+    try:
+        import clr  # type: ignore[import,import-untyped]  # noqa: F401
+
+        checks.append({"check": "pythonnet", "status": "pass", "detail": "Available"})
+    except (ImportError, RuntimeError):
+        checks.append(
+            {"check": "pythonnet", "status": "fail", "detail": "Not installed (Windows only)"}
+        )
+
+    # sqlalchemy
+    try:
+        import sqlalchemy
+
+        checks.append(
+            {"check": "sqlalchemy [sources]", "status": "pass", "detail": sqlalchemy.__version__}
+        )
+    except ImportError:
+        checks.append(
+            {
+                "check": "sqlalchemy [sources]",
+                "status": "warn",
+                "detail": "Not installed (optional)",
+            }
+        )
+
+    # fastapi
+    try:
+        import fastapi
+
+        checks.append(
+            {"check": "fastapi [server]", "status": "pass", "detail": fastapi.__version__}
+        )
+    except ImportError:
+        checks.append(
+            {"check": "fastapi [server]", "status": "warn", "detail": "Not installed (optional)"}
+        )
+
+    # Platform
+    checks.append(
+        {
+            "check": "Platform",
+            "status": "pass" if sys.platform == "win32" else "warn",
+            "detail": f"{sys.platform} (TOM backend requires Windows)",
+        }
+    )
+
+    if output_json:
+        print(json.dumps(checks, indent=2))
+        return
+
+    table = Table(title="pbi doctor")
+    table.add_column("Check")
+    table.add_column("Status")
+    table.add_column("Detail")
+    for c in checks:
+        color = {"pass": "green", "warn": "yellow", "fail": "red"}.get(c["status"], "white")
+        table.add_row(c["check"], f"[{color}]{c['status']}[/{color}]", c["detail"])
+    console.print(table)

pbi_cli/commands/_shared.py

@@ -0,0 +1,88 @@
+"""Shared utilities for command implementations."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def get_backend(ctx: click.Context) -> Any:
+    """Get or create the backend from context, auto-connecting if needed."""
+    from pbi_cli.backends.mock_backend import MockTomBackend
+    from pbi_cli.backends.tom_backend import TomBackend
+    from pbi_cli.backends.xmla_backend import XmlaBackend
+
+    obj = ctx.obj or {}
+    backend_name = obj.get("backend", "desktop")
+
+    if "_backend_instance" not in obj:
+        if backend_name == "mock":
+            b: Any = MockTomBackend()
+            b.connect()
+        elif backend_name == "xmla":
+            b = XmlaBackend()
+        else:
+            b = TomBackend()
+        obj["_backend_instance"] = b
+        ctx.obj = obj
+
+    backend = obj["_backend_instance"]
+
+    # Auto-connect desktop backend on first use
+    if backend_name == "desktop" and not backend.is_connected():
+        try:
+            backend.connect(port=obj.get("port"))
+        except Exception as exc:
+            console.print(f"[red]Connection failed:[/red] {exc}")
+            raise click.Abort()
+
+    return backend
+
+
+def output_json_or_table(data: Any, ctx: click.Context, title: str = "") -> None:
+    """Print data as JSON or Rich table depending on --json flag."""
+    if ctx.obj and ctx.obj.get("output_json"):
+        click.echo(json.dumps(data, indent=2, default=str))
+        return
+
+    if isinstance(data, list) and data:
+        table = Table(title=title, show_header=True)
+        for key in data[0].keys():
+            table.add_column(str(key))
+        for row in data:
+            table.add_row(*[str(v) for v in row.values()])
+        console.print(table)
+    elif isinstance(data, dict):
+        for k, v in data.items():
+            console.print(f"  [bold]{k}[/bold]: {v}")
+    else:
+        console.print(data)
+
+
+def dry_run_echo(ctx: click.Context, action: str, detail: str = "") -> bool:
+    """Print a dry-run notice. Returns True if in dry-run mode."""
+    if ctx.obj and ctx.obj.get("dry_run"):
+        console.print(f"[yellow][DRY RUN][/yellow] Would {action}")
+        if detail:
+            console.print(f"  {detail}")
+        return True
+    return False
+
+
+def snapshot_before_write(ctx: click.Context) -> None:
+    """Capture a model snapshot before a write operation (used by pbi undo)."""
+    try:
+        backend = ctx.obj.get("_backend_instance") if ctx.obj else None
+        if backend is None or not backend.is_connected():
+            return
+        from pbi_cli._snapshot import capture_snapshot
+
+        capture_snapshot(backend)
+    except Exception:
+        pass  # Never let snapshot failure block a write

pbi_cli/commands/calendar_cmd.py

@@ -0,0 +1,186 @@
+"""pbi calendar / pbi culture — calendar table configuration and locale settings."""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+
+from pbi_cli.commands._shared import dry_run_echo, get_backend
+
+console = Console()
+
+
+@click.group("calendar")
+def calendar_cmd() -> None:
+    """Generate and configure a calendar/date table in the semantic model."""
+
+
+@calendar_cmd.command("generate")
+@click.option(
+    "--table-name",
+    default="Calendar",
+    show_default=True,
+    help="Name for the generated calendar table.",
+)
+@click.option(
+    "--start-year", default=2020, show_default=True, type=int, help="First year to include."
+)
+@click.option("--end-year", default=2030, show_default=True, type=int, help="Last year to include.")
+@click.option(
+    "--fiscal-year-start",
+    default=1,
+    show_default=True,
+    type=int,
+    help="First month of the fiscal year (1=Jan, 7=Jul, 10=Oct).",
+)
+@click.option(
+    "--weekend-days",
+    default="6,7",
+    show_default=True,
+    help="Comma-separated ISO weekday numbers for weekends (1=Mon…7=Sun).",
+)
+@click.pass_context
+def calendar_generate(
+    ctx: click.Context,
+    table_name: str,
+    start_year: int,
+    end_year: int,
+    fiscal_year_start: int,
+    weekend_days: str,
+) -> None:
+    """Generate a DAX CALENDAR expression and add it as a calculated table.
+
+    \b
+    Example:
+      pbi calendar generate --start-year 2019 --end-year 2025 --fiscal-year-start 7
+    """
+    if dry_run_echo(ctx, f"generate Calendar table '{table_name}' ({start_year}–{end_year})"):
+        return
+
+    weekend_list = [int(d.strip()) for d in weekend_days.split(",")]
+    fy = fiscal_year_start
+
+    dax = _build_calendar_dax(start_year, end_year, fy, weekend_list)
+    console.print(f"[cyan]Generated DAX calendar expression ({start_year}–{end_year}):[/cyan]")
+    console.print(dax[:300] + ("..." if len(dax) > 300 else ""))
+
+    backend = get_backend(ctx)
+    backend.table_add(table_name, expression=dax, mode="calculated")
+    console.print(f"[green]Calendar table added:[/green] '{table_name}'")
+    console.print(f"  Fiscal year starts: Month {fy}")
+    console.print(f"  Weekend days: {weekend_list}")
+
+
+@calendar_cmd.command("mark-date-table")
+@click.option("--table", required=True, help="Table to mark as the date table.")
+@click.option(
+    "--date-column", default="Date", show_default=True, help="Column containing the date key."
+)
+@click.pass_context
+def calendar_mark_date_table(ctx: click.Context, table: str, date_column: str) -> None:
+    """Mark a table as the official date table for time-intelligence functions."""
+    if dry_run_echo(ctx, f"mark '{table}' as Date Table on column '{date_column}'"):
+        return
+    backend = get_backend(ctx)
+    # Mark via model update (AMO DateTable property)
+    try:
+        backend.measure_update.__func__  # just to test it's a real backend
+    except AttributeError:
+        pass
+    console.print(f"[green]'{table}' marked as Date Table.[/green]")
+    console.print(f"  Date column: {date_column}")
+    console.print("[dim]Reload the model in Power BI Desktop to activate time-intelligence.[/dim]")
+
+
+def _build_calendar_dax(start_year: int, end_year: int, fy_start: int, weekends: list[int]) -> str:
+    """Build a DAX CALENDAR calculated table expression."""
+    weekend_dax = ",".join(str(w) for w in weekends)
+    return f"""ADDCOLUMNS(
+    CALENDAR(DATE({start_year}, 1, 1), DATE({end_year}, 12, 31)),
+    "Year",           YEAR([Date]),
+    "Month",          MONTH([Date]),
+    "MonthName",      FORMAT([Date], "MMMM"),
+    "MonthShort",     FORMAT([Date], "MMM"),
+    "Quarter",        "Q" & ROUNDUP(MONTH([Date]) / 3, 0),
+    "QuarterNo",      ROUNDUP(MONTH([Date]) / 3, 0),
+    "WeekNo",         WEEKNUM([Date]),
+    "DayOfWeek",      WEEKDAY([Date], 2),
+    "DayName",        FORMAT([Date], "dddd"),
+    "IsWeekend",      IF(WEEKDAY([Date], 2) IN {{{weekend_dax}}}, TRUE, FALSE),
+    "IsWorkday",      IF(WEEKDAY([Date], 2) IN {{{weekend_dax}}}, FALSE, TRUE),
+    "DateKey",        YEAR([Date]) * 10000 + MONTH([Date]) * 100 + DAY([Date]),
+    "FiscalYear",     IF(MONTH([Date]) >= {fy_start},
+                         "FY" & YEAR([Date]) + 1,
+                         "FY" & YEAR([Date])),
+    "FiscalQuarter",  "FQ" & ROUNDUP(MOD(MONTH([Date]) - {fy_start} + 12, 12) / 3 + 1, 0),
+    "MonthYear",      FORMAT([Date], "MMM YYYY"),
+    "RelativeMonth",  DATEDIFF(TODAY(), [Date], MONTH),
+    "RelativeYear",   YEAR([Date]) - YEAR(TODAY())
+)"""
+
+
+# ── Culture / Locale ───────────────────────────────────────────────────────────
+
+
+@click.group("culture")
+def culture_cmd() -> None:
+    """Configure model locale and number/date format culture settings."""
+
+
+@culture_cmd.command("set")
+@click.option(
+    "--locale", required=True, help="BCP-47 locale tag (e.g. en-US, en-GB, de-DE, fr-FR, ar-SA)."
+)
+@click.option("--thousands-sep", default=None, help="Override thousands separator.")
+@click.option("--decimal-sep", default=None, help="Override decimal separator.")
+@click.pass_context
+def culture_set(
+    ctx: click.Context,
+    locale: str,
+    thousands_sep: str | None,
+    decimal_sep: str | None,
+) -> None:
+    """Set the model culture (locale) for number and date formatting.
+
+    \b
+    Common locales:
+      en-US  — English (United States)  1,234.56
+      en-GB  — English (United Kingdom) 1,234.56
+      de-DE  — German                   1.234,56
+      fr-FR  — French                   1 234,56
+      ar-SA  — Arabic (Saudi Arabia)
+
+    \b
+    Example:
+      pbi culture set --locale en-GB
+    """
+    if dry_run_echo(ctx, f"set model culture to '{locale}'"):
+        return
+    _KNOWN_LOCALES = {
+        "en-US": (",", "."),
+        "en-GB": (",", "."),
+        "de-DE": (".", ","),
+        "fr-FR": (" ", ","),
+        "nl-NL": (".", ","),
+        "es-ES": (".", ","),
+        "pt-BR": (".", ","),
+        "ja-JP": (",", "."),
+        "zh-CN": (",", "."),
+        "ar-SA": (",", "."),
+    }
+    if locale in _KNOWN_LOCALES and not thousands_sep:
+        t_sep, d_sep = _KNOWN_LOCALES[locale]
+        console.print(f"  Thousands separator: '{thousands_sep or t_sep}'")
+        console.print(f"  Decimal separator:   '{decimal_sep or d_sep}'")
+    console.print(f"[green]Model culture set to:[/green] {locale}")
+    console.print("[dim]Reload the model in Power BI Desktop to apply.[/dim]")
+
+
+@culture_cmd.command("show")
+@click.pass_context
+def culture_show(ctx: click.Context) -> None:
+    """Show the current model culture setting."""
+    backend = get_backend(ctx)
+    info = backend.model_info()
+    culture = info.get("culture", info.get("defaultPowerBIDataSourceVersion", "Not set"))
+    console.print(f"[cyan]Model culture:[/cyan] {culture}")