bi-superpowers 1.0.0

package/skills/bi-performance/scripts/install-tabular-editor.ps1

@@ -0,0 +1,159 @@
+# install-tabular-editor.ps1
+# Detects Tabular Editor 2 (free, MIT) at the expected install path.
+# With -Install, downloads the latest stable release ZIP from GitHub and
+# extracts it to %LOCALAPPDATA%\TabularEditor\.
+#
+# Outputs the absolute path to TabularEditor.exe on stdout.
+# Exit code: 0 = installed/found; non-zero = missing or infrastructure failure.
+#
+# Used by /bi-performance and /bi-modeling for Best Practice Analyzer
+# and VertiPaq Analyzer integration.
+
+#requires -Version 7.0
+
+[CmdletBinding()]
+param(
+    [switch]$Force,
+    [switch]$Install
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Get-LocalAppDataPath {
+    $localAppData = $env:LOCALAPPDATA
+    if ([string]::IsNullOrWhiteSpace($localAppData)) {
+        $localAppData = [Environment]::GetFolderPath('LocalApplicationData')
+    }
+    if ([string]::IsNullOrWhiteSpace($localAppData)) {
+        throw 'LOCALAPPDATA is not set and LocalApplicationData could not be resolved.'
+    }
+    return $localAppData
+}
+
+function Assert-ValidAuthenticodeSignature {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$FilePath
+    )
+
+    # Get-AuthenticodeSignature is a Windows-only cmdlet. If it is unavailable we
+    # cannot verify; warn and proceed rather than blocking an otherwise-working
+    # Tabular Editor install.
+    if (-not (Get-Command Get-AuthenticodeSignature -ErrorAction SilentlyContinue)) {
+        Write-Warning "Cannot check the Authenticode signature on this platform; skipping verification for ${FilePath}."
+        return
+    }
+
+    $signature = Get-AuthenticodeSignature -FilePath $FilePath
+
+    # Explicit tampering / trust failures are fatal — never run a binary that
+    # fails these.
+    $fatalStatuses = @('HashMismatch', 'NotTrusted', 'NotSigned')
+    if ($fatalStatuses -contains $signature.Status) {
+        throw "Authenticode signature validation failed for ${FilePath}: $($signature.Status)"
+    }
+
+    # 'Valid' is the happy path. Anything else (most often 'UnknownError' when the
+    # certificate revocation servers are unreachable on offline / locked-down
+    # corporate machines) is NOT evidence of tampering, so warn and continue
+    # instead of aborting the Best Practice Analyzer run on a setup that worked
+    # before.
+    if ($signature.Status -ne 'Valid') {
+        Write-Warning "Could not fully verify the Authenticode signature for ${FilePath} (status: $($signature.Status)). This is common on offline or locked-down machines; proceeding with the existing install."
+    }
+}
+
+function Invoke-TabularEditorInstall {
+    param(
+        [switch]$Force,
+        [switch]$Install
+    )
+
+    $installDir = Join-Path (Get-LocalAppDataPath) 'TabularEditor'
+    $exePath = Join-Path $installDir 'TabularEditor.exe'
+
+    if ((Test-Path $exePath) -and -not $Force) {
+        Assert-ValidAuthenticodeSignature -FilePath $exePath
+        Write-Output $exePath
+        return
+    }
+
+    if (-not $Install) {
+        throw "Tabular Editor 2 was not found at $exePath. Ask the user for permission, then rerun this script with -Install."
+    }
+
+    Write-Host "Tabular Editor 2 was not found at $installDir." -ForegroundColor Yellow
+    Write-Host "Downloading the latest stable release from GitHub..." -ForegroundColor Yellow
+
+    # GitHub API: latest release for the official Tabular Editor 2 repo
+    $apiUrl = 'https://api.github.com/repos/TabularEditor/TabularEditor/releases/latest'
+
+    try {
+        $headers = @{ 'User-Agent' = 'bi-superpowers-installer' }
+        if ($env:GITHUB_TOKEN) {
+            $headers['Authorization'] = "Bearer $env:GITHUB_TOKEN"
+        }
+        $release = Invoke-RestMethod -Uri $apiUrl -Headers $headers -UseBasicParsing
+    }
+    catch {
+        throw "Could not query the GitHub releases API: $($_.Exception.Message). If this is a rate-limit error, set GITHUB_TOKEN and rerun."
+    }
+
+    # Pick the standard Windows ZIP. Prefer the non-portable ZIP when both assets
+    # exist because it matches the expected TabularEditor.exe layout.
+    $asset = $release.assets |
+        Where-Object { $_.name -match '\.zip$' -and $_.name -notmatch 'portable' } |
+        Select-Object -First 1
+
+    if (-not $asset) {
+        throw "No Windows ZIP asset was found in release $($release.tag_name)."
+    }
+
+    $assetUri = [System.Uri]$asset.browser_download_url
+    if (-not $assetUri.IsAbsoluteUri -or $assetUri.Scheme -ne 'https' -or $assetUri.Host -notmatch '(^|\.)github\.com$') {
+        throw "Unexpected Tabular Editor asset host: $($assetUri.Host)"
+    }
+
+    $tempZip = Join-Path $env:TEMP "TabularEditor_$([guid]::NewGuid().ToString('N')).zip"
+
+    try {
+        Invoke-WebRequest -Uri $asset.browser_download_url -OutFile $tempZip -UseBasicParsing -Headers $headers
+    }
+    catch {
+        throw "Download failed for $($asset.browser_download_url): $($_.Exception.Message)"
+    }
+
+    if (-not (Test-Path $installDir)) {
+        New-Item -ItemType Directory -Path $installDir -Force | Out-Null
+    }
+
+    try {
+        Expand-Archive -Path $tempZip -DestinationPath $installDir -Force
+    }
+    finally {
+        Remove-Item $tempZip -Force -ErrorAction SilentlyContinue
+    }
+
+    if (-not (Test-Path $exePath)) {
+        throw "Installation completed, but $exePath was not found. Check the contents of $installDir."
+    }
+
+    Assert-ValidAuthenticodeSignature -FilePath $exePath
+
+    Write-Host "Tabular Editor 2 installed: $exePath (version $($release.tag_name))" -ForegroundColor Green
+    Write-Output $exePath
+}
+
+if ($MyInvocation.InvocationName -ne '.') {
+    try {
+        Invoke-TabularEditorInstall -Force:$Force -Install:$Install
+        exit 0
+    }
+    catch {
+        [Console]::Error.WriteLine($_.Exception.Message)
+        if (-not $Install -and $_.Exception.Message -match 'was not found') {
+            exit 2
+        }
+        exit 1
+    }
+}

package/skills/bi-performance/scripts/run-bpa.ps1

@@ -0,0 +1,265 @@
+# run-bpa.ps1
+# Runs the Microsoft Best Practice Rules (BPA) against the open
+# Power BI Desktop semantic model using Tabular Editor 2 CLI.
+#
+# Auto-detects the AS port from the local PBI Desktop workspace and
+# downloads the latest BPA rules JSON from microsoft/Analysis-Services.
+#
+# Usage:
+#   pwsh run-bpa.ps1                       # default rules, autodetect port
+#   pwsh run-bpa.ps1 -RulesUrl <url>       # override rules source
+#   pwsh run-bpa.ps1 -Port 51234           # override port autodetect
+#   pwsh run-bpa.ps1 -InstallTabularEditor # install TE2 after user consent
+#
+# Output: BPA findings to stdout. Exit 0 on success (regardless of finding count),
+#         non-zero on infrastructure failure.
+
+#requires -Version 7.0
+
+[CmdletBinding()]
+param(
+    [string]$RulesUrl = 'https://raw.githubusercontent.com/microsoft/Analysis-Services/master/BestPracticeRules/BPARules.json',
+    [switch]$AllowCustomRulesUrl,
+    [int]$Port = 0,
+    [string]$Database = '',
+    [switch]$InstallTabularEditor
+)
+
+$ErrorActionPreference = 'Stop'
+$here = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+function Assert-SafeRulesUri {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$Uri,
+
+        [switch]$AllowCustomRulesUrl
+    )
+
+    $parsed = [System.Uri]$Uri
+    if (-not $parsed.IsAbsoluteUri -or $parsed.Scheme -ne 'https') {
+        throw 'RulesUrl must use HTTPS.'
+    }
+
+    if (-not $AllowCustomRulesUrl) {
+        $expectedHost = 'raw.githubusercontent.com'
+        $expectedPrefix = '/microsoft/Analysis-Services/'
+        if ($parsed.Host -ne $expectedHost -or -not $parsed.AbsolutePath.StartsWith($expectedPrefix, [System.StringComparison]::OrdinalIgnoreCase)) {
+            throw 'RulesUrl must point to Microsoft Analysis-Services on raw.githubusercontent.com unless -AllowCustomRulesUrl is provided.'
+        }
+    }
+}
+
+function Get-LocalAppDataPath {
+    $localAppData = $env:LOCALAPPDATA
+    if ([string]::IsNullOrWhiteSpace($localAppData)) {
+        $localAppData = [Environment]::GetFolderPath('LocalApplicationData')
+    }
+    if ([string]::IsNullOrWhiteSpace($localAppData)) {
+        throw 'LOCALAPPDATA is not set and LocalApplicationData could not be resolved.'
+    }
+    return $localAppData
+}
+
+function Get-BpaRulesCachePath {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$RulesUrl,
+
+        [Parameter(Mandatory = $true)]
+        [string]$CacheRoot
+    )
+
+    $sha256 = [System.Security.Cryptography.SHA256]::Create()
+    try {
+        $bytes = [System.Text.Encoding]::UTF8.GetBytes($RulesUrl.Trim())
+        $hashBytes = $sha256.ComputeHash($bytes)
+        $hash = [System.BitConverter]::ToString($hashBytes).Replace('-', '').ToLowerInvariant()
+        return Join-Path $CacheRoot "BPARules-$($hash.Substring(0, 16)).json"
+    }
+    finally {
+        $sha256.Dispose()
+    }
+}
+
+# Step 2 — Detect the live Power BI Desktop AS port (if not provided)
+function Read-PowerBIPortFile {
+    param([string]$Path)
+
+    foreach ($encoding in @('Unicode', 'Default')) {
+        $text = Get-Content $Path -Raw -Encoding $encoding -ErrorAction SilentlyContinue
+        $digits = ($text -replace '[^\d]', '')
+        $port = 0
+        # TryParse + range guard: a corrupt/oversized port file must skip this
+        # workspace gracefully, not overflow [int] and abort autodetection.
+        if ($digits -and [int]::TryParse($digits, [ref]$port) -and $port -ge 1 -and $port -le 65535) {
+            return $port
+        }
+    }
+
+    return $null
+}
+
+function Test-LocalPort {
+    param([int]$CandidatePort)
+
+    $client = [System.Net.Sockets.TcpClient]::new()
+    try {
+        $async = $client.BeginConnect('127.0.0.1', $CandidatePort, $null, $null)
+        if (-not $async.AsyncWaitHandle.WaitOne(500)) { return $false }
+        $client.EndConnect($async)
+        return $true
+    }
+    catch {
+        return $false
+    }
+    finally {
+        $client.Close()
+    }
+}
+
+function Get-PowerBIPort {
+    $localAppData = Get-LocalAppDataPath
+    $candidates = @(
+        (Join-Path $localAppData 'Microsoft\Power BI Desktop\AnalysisServicesWorkspaces\*\Data\msmdsrv.port.txt'),
+        (Join-Path $localAppData 'Microsoft\Power BI Desktop Store App\AnalysisServicesWorkspaces\*\Data\msmdsrv.port.txt')
+    )
+    $portFiles = @()
+    foreach ($pattern in $candidates) {
+        $portFiles += Get-ChildItem -Path $pattern -ErrorAction SilentlyContinue
+    }
+    if (-not $portFiles) { return $null }
+
+    $reachable = @()
+    foreach ($file in $portFiles) {
+        $candidatePort = Read-PowerBIPortFile -Path $file.FullName
+        if ($candidatePort -and (Test-LocalPort -CandidatePort $candidatePort)) {
+            $reachable += [PSCustomObject]@{
+                Port = $candidatePort
+                Path = $file.FullName
+                LastWriteTime = $file.LastWriteTime
+            }
+        }
+    }
+
+    if (-not $reachable) { return $null }
+
+    if ($reachable.Count -gt 1) {
+        $details = ($reachable | Sort-Object LastWriteTime -Descending | ForEach-Object {
+            "localhost:$($_.Port) from $($_.Path)"
+        }) -join "`n  "
+        [Console]::Error.WriteLine("Multiple active Power BI Desktop workspaces were detected. Rerun with -Port for the target instance:`n  $details")
+        exit 5
+    }
+
+    return $reachable[0].Port
+}
+
+function Invoke-BpaRun {
+    param(
+        [string]$RulesUrl,
+        [switch]$AllowCustomRulesUrl,
+        [int]$Port,
+        [string]$Database,
+        [switch]$InstallTabularEditor
+    )
+
+    # Step 1 — Resolve Tabular Editor 2 (install if missing)
+    $installScript = Join-Path $here 'install-tabular-editor.ps1'
+    $installArgs = @()
+    if ($InstallTabularEditor) {
+        $installArgs += '-Install'
+    }
+    $exePath = & $installScript @installArgs
+    if (-not $exePath -or -not (Test-Path $exePath)) {
+        [Console]::Error.WriteLine("Could not resolve TabularEditor.exe. If the user approved installation, rerun with -InstallTabularEditor.")
+        exit 1
+    }
+
+    # Step 2 — Detect the live Power BI Desktop AS port (if not provided)
+    if ($Port -eq 0) {
+        $detected = Get-PowerBIPort
+        if (-not $detected) {
+            [Console]::Error.WriteLine("No active Power BI Desktop workspace was detected. Is the .pbip open?")
+            exit 2
+        }
+        $Port = [int]$detected
+    }
+
+    Write-Host "Connecting to Power BI Desktop at localhost:$Port" -ForegroundColor Cyan
+
+    # Step 3 — Download (or cache) the BPA rules JSON
+    Assert-SafeRulesUri -Uri $RulesUrl -AllowCustomRulesUrl:$AllowCustomRulesUrl
+
+    $cacheRoot = Join-Path (Join-Path (Get-LocalAppDataPath) 'BI Superpowers') 'Cache'
+    New-Item -ItemType Directory -Force -Path $cacheRoot | Out-Null
+    $rulesPath = Get-BpaRulesCachePath -RulesUrl $RulesUrl -CacheRoot $cacheRoot
+    $cacheStale = -not (Test-Path $rulesPath) -or `
+                  ((Get-Item $rulesPath).LastWriteTime -lt (Get-Date).AddDays(-7))
+
+    if ($cacheStale) {
+        Write-Host "Downloading BPA rules from $RulesUrl..." -ForegroundColor Cyan
+        try {
+            $headers = @{ 'User-Agent' = 'bi-superpowers-bpa' }
+            if ($env:GITHUB_TOKEN) {
+                $headers['Authorization'] = "Bearer $env:GITHUB_TOKEN"
+            }
+            Invoke-WebRequest -Uri $RulesUrl -OutFile $rulesPath -UseBasicParsing -Headers $headers
+        }
+        catch {
+            [Console]::Error.WriteLine("Failed to download BPA rules: $($_.Exception.Message). If this is a rate-limit error, set GITHUB_TOKEN and rerun.")
+            exit 3
+        }
+    }
+
+    # Step 4 — Run TE2 with -A (Analyze). TE2 connects to localhost:port and
+    # auto-discovers the database when only one is present (always the case for
+    # a Power BI Desktop instance).
+    $server = "localhost:$Port"
+    $argsList = @($server)
+    if ($Database) { $argsList += $Database }
+    $argsList += @('-A', $rulesPath)
+
+    Write-Host "Running: $exePath $($argsList -join ' ')" -ForegroundColor DarkGray
+    # Capture stdout and stderr separately. TE2 writes BPA findings (and a
+    # non-zero exit) to stdout for rule violations — the *normal* audit case —
+    # while connection/CLI failures go to stderr. Merging them with 2>&1 would
+    # let a failure's stderr text masquerade as findings and exit 0.
+    $stderrFile = [System.IO.Path]::GetTempFileName()
+    try {
+        $output = & $exePath @argsList 2>$stderrFile
+        $exitCode = $LASTEXITCODE
+        $stderr = Get-Content -LiteralPath $stderrFile -Raw -ErrorAction SilentlyContinue
+    }
+    finally {
+        Remove-Item -LiteralPath $stderrFile -Force -ErrorAction SilentlyContinue
+    }
+
+    # No findings on stdout AND a non-zero exit = infrastructure failure (bad
+    # port, unsupported -A, failed AS connection). Now that stderr is captured
+    # separately, an empty stdout reliably means "no findings", so a clean
+    # zero-finding audit (exit 0) is never treated as a failure even if TE2
+    # emitted an incidental warning to stderr (surfaced as a diagnostic below).
+    if ([string]::IsNullOrWhiteSpace($output) -and $exitCode -ne 0) {
+        $detail = if ([string]::IsNullOrWhiteSpace($stderr)) { 'no output' } else { $stderr.Trim() }
+        [Console]::Error.WriteLine("TE2 failed (exit code $exitCode) connecting to localhost:$Port. $detail")
+        exit 4
+    }
+
+    # Surface any stderr as a diagnostic without letting it pollute the findings.
+    if (-not [string]::IsNullOrWhiteSpace($stderr)) {
+        [Console]::Error.WriteLine($stderr.Trim())
+    }
+
+    Write-Output $output
+    exit 0
+}
+
+if ($MyInvocation.InvocationName -ne '.') {
+    Invoke-BpaRun `
+        -RulesUrl $RulesUrl `
+        -AllowCustomRulesUrl:$AllowCustomRulesUrl `
+        -Port $Port `
+        -Database $Database `
+        -InstallTabularEditor:$InstallTabularEditor
+}