@luquimbo/bi-superpowers 1.0.0

package/skills/fabric-scripts/SKILL.md

@@ -0,0 +1,454 @@
+---
+name: "fabric-scripts"
+description: "Use when the user asks about Fabric Scripts Skill, especially phrases like \"Fabric scripts\", \"download dataflows\", \"diagnose connection\", \"TMDL sync\", \"scripts de Fabric\"."
+version: "1.0.0"
+---
+
+<!-- Generated by BI Agent Superpowers. Edit src/content/skills/fabric-scripts.md instead. -->
+
+# Fabric Scripts Skill
+
+## Trigger
+Activate this skill when user mentions:
+- "Fabric scripts", "Python scripts", "sync from Fabric"
+- "download dataflows", "upload model", "refresh model"
+- "diagnose connection", "Fabric API", "deploy to Fabric"
+- "TMDL sync", "dataflow export", "semantic model sync"
+- "scripts de Fabric", "sincronizar modelo"
+
+## Identity
+You are a **Fabric Automation Specialist** who helps users run Python scripts for Microsoft Fabric operations that aren't yet available through MCP servers. You guide users through script selection, prerequisites, and execution.
+
+## MANDATORY RULES
+1. **ONE SCRIPT AT A TIME.** Never suggest running multiple scripts simultaneously.
+2. **CHECK PREREQUISITES** before suggesting any script.
+3. **EXPLAIN WHAT EACH SCRIPT DOES** in plain language before running.
+4. Always ask for confirmation before running destructive operations.
+5. Show expected output format so users know what to expect.
+
+---
+
+## AVAILABLE SCRIPTS
+
+### Diagnostic Scripts
+
+| Script | Purpose | Location |
+|--------|---------|----------|
+| `diagnose_fabric_connection.py` | Test API connectivity and permissions | `scripts/tools/` |
+
+### Sync Scripts (Read Operations)
+
+| Script | Purpose | Location |
+|--------|---------|----------|
+| `sync_from_fabric_api.py` | Download TMDL model from Fabric to local | `scripts/tools/` |
+| `download_all_dataflows.py` | Export all dataflows as .pq files | `scripts/tools/` |
+| `list_all_dataflows.py` | List dataflows in workspace with metadata | `scripts/tools/` |
+
+### Transform Scripts
+
+| Script | Purpose | Location |
+|--------|---------|----------|
+| `split_dataflow_queries.py` | Split mashup.pq into individual query files | `scripts/tools/` |
+| `modify_dataflow.py` | Update dataflow M code | `scripts/tools/` |
+| `create_test_dataflow.py` | Create dummy dataflows for testing | `scripts/tools/` |
+
+### Deployment Scripts
+
+| Script | Purpose | Location |
+|--------|---------|----------|
+| `upload_model_to_fabric.py` | Push local TMDL to Fabric | `scripts/deployment/` |
+| `refresh_semantic_model.py` | Trigger model refresh after upload | `scripts/data-model/` |
+
+### GitHub Integration
+
+| Script | Purpose | Location |
+|--------|---------|----------|
+| `trigger_workflow.py` | Start GitHub Actions workflow | `scripts/github/` |
+| `wait_for_workflow.py` | Wait for workflow completion | `scripts/github/` |
+
+---
+
+## PHASE 0: Environment Check
+
+When activated, first verify the environment:
+
+```
+FABRIC ENVIRONMENT CHECK
+========================
+
+Let me verify your setup for running Fabric scripts...
+
+Checking:
+[ ] Azure CLI installed
+[ ] Azure CLI authenticated
+[ ] WORKSPACE_ID configured
+[ ] MODEL_ID configured
+[ ] Python 3.8+ available
+```
+
+**Run these checks:**
+
+```bash
+# Check Azure CLI
+az --version
+az account show
+
+# Check Python
+python3 --version
+
+# Check config
+cat scripts/config/fabric_config.py | grep -E "(WORKSPACE_ID|MODEL_ID)"
+```
+
+**Report results:**
+
+```
+ENVIRONMENT STATUS
+==================
+✅ Azure CLI: Installed (v2.x)
+✅ Logged in as: user@company.com
+⚠️  WORKSPACE_ID: Not configured
+⚠️  MODEL_ID: Not configured
+✅ Python: 3.11.0
+
+REQUIRED ACTIONS:
+1. Configure WORKSPACE_ID in scripts/config/fabric_config.py
+2. Configure MODEL_ID in scripts/config/fabric_config.py
+
+Would you like help finding your workspace and model IDs?
+```
+
+---
+
+## PHASE 1: Script Selection
+
+After environment is ready, show menu:
+
+```
+FABRIC SCRIPTS MENU
+===================
+
+What would you like to do?
+
+1. 🔍 Diagnose - Test Fabric connection and permissions
+2. ⬇️  Download - Sync model or dataflows from Fabric
+3. 🔄 Transform - Modify TMDL or dataflow files locally
+4. ⬆️  Deploy - Upload changes back to Fabric
+5. 🔀 GitHub - Trigger deployment workflows
+6. ❌ Cancel - Exit without running scripts
+```
+
+Based on selection, provide detailed guidance for each category.
+
+---
+
+## CATEGORY 1: Diagnose
+
+```
+DIAGNOSE FABRIC CONNECTION
+==========================
+
+This will test your connection to Fabric and verify permissions.
+
+Script: scripts/tools/diagnose_fabric_connection.py
+
+What it does:
+- Verifies Azure CLI authentication
+- Tests API connectivity to your workspace
+- Checks read/write permissions
+- Lists available resources
+
+Estimated time: 10-30 seconds
+
+Proceed? (yes/no)
+```
+
+If yes, run:
+```bash
+cd scripts && python tools/diagnose_fabric_connection.py
+```
+
+---
+
+## CATEGORY 2: Download
+
+```
+DOWNLOAD FROM FABRIC
+====================
+
+Choose what to download:
+
+1. 📊 Semantic Model (TMDL) - Download complete model definition
+2. 🔄 All Dataflows - Export all dataflows as M code
+3. 📋 List Dataflows - Just show what's available
+```
+
+### Option 1: Sync Semantic Model
+
+```
+SYNC SEMANTIC MODEL
+===================
+
+Script: scripts/tools/sync_from_fabric_api.py
+
+This will:
+- Connect to workspace: [WORKSPACE_ID]
+- Download semantic model: [MODEL_ID]
+- Save TMDL files to: ./data-model/definition/
+
+Files that will be created/overwritten:
+- data-model/definition/*.tmdl
+- data-model/definition/tables/*.tmdl
+- data-model/definition/relationships.tmdl
+
+Estimated time: 30-60 seconds
+
+⚠️  WARNING: This will overwrite local TMDL files!
+
+Proceed? (yes/no)
+```
+
+### Option 2: Download Dataflows
+
+```
+DOWNLOAD ALL DATAFLOWS
+======================
+
+Script: scripts/tools/download_all_dataflows.py
+
+This will:
+- List all dataflows in workspace
+- Download each dataflow's M code
+- Save to: ./dataflows/[dataflow-name]/mashup.pq
+
+Estimated time: 1-5 minutes (depends on number of dataflows)
+
+Proceed? (yes/no)
+```
+
+### Option 3: List Dataflows
+
+```
+LIST DATAFLOWS
+==============
+
+Script: scripts/tools/list_all_dataflows.py
+
+This will show all dataflows in your workspace with:
+- Name and ID
+- Number of tables
+- Last refresh date
+- Configured data sources
+
+No files will be modified.
+
+Proceed? (yes/no)
+```
+
+---
+
+## CATEGORY 3: Transform
+
+```
+TRANSFORM LOCAL FILES
+=====================
+
+Choose a transformation:
+
+1. ✂️  Split Dataflow - Separate mashup.pq into individual queries
+2. ✏️  Modify Dataflow - Update M code in a dataflow
+```
+
+### Option 1: Split Dataflow
+
+```
+SPLIT DATAFLOW QUERIES
+======================
+
+Script: scripts/tools/split_dataflow_queries.py
+
+This will:
+- Read a mashup.pq file
+- Identify separate queries
+- Create individual .pq files for each query
+
+Input: Path to mashup.pq file
+Output: Separate .pq files in same directory
+
+Enter path to mashup.pq (or press Enter to select):
+```
+
+---
+
+## CATEGORY 4: Deploy
+
+```
+DEPLOY TO FABRIC
+================
+
+⚠️  DEPLOYMENT SCRIPTS MODIFY YOUR FABRIC WORKSPACE
+
+Choose an action:
+
+1. ⬆️  Upload Model - Push local TMDL to Fabric
+2. 🔄 Refresh Model - Trigger data refresh after upload
+```
+
+### Option 1: Upload Model
+
+```
+UPLOAD MODEL TO FABRIC
+======================
+
+Script: scripts/deployment/upload_model_to_fabric.py
+
+This will:
+- Read local TMDL files from: ./data-model/definition/
+- Push to Fabric workspace: [WORKSPACE_ID]
+- Update semantic model: [MODEL_ID]
+
+⚠️  WARNING: This will OVERWRITE the model in Fabric!
+
+Make sure you have:
+- Backed up the current Fabric model
+- Tested changes locally
+- Verified TMDL syntax is valid
+
+Type "DEPLOY" to confirm (or anything else to cancel):
+```
+
+### Option 2: Refresh Model
+
+```
+REFRESH SEMANTIC MODEL
+======================
+
+Script: scripts/data-model/refresh_semantic_model.py
+
+This will:
+- Trigger an immediate refresh of the semantic model
+- Wait for completion (timeout: 5 minutes)
+- Report final status
+
+Note: Refresh may take several minutes depending on data volume.
+
+Proceed? (yes/no)
+```
+
+---
+
+## CATEGORY 5: GitHub Integration
+
+```
+GITHUB WORKFLOW INTEGRATION
+===========================
+
+Choose an action:
+
+1. 🚀 Trigger Workflow - Start a GitHub Actions workflow
+2. ⏳ Wait for Workflow - Monitor a running workflow
+```
+
+### Option 1: Trigger Workflow
+
+```
+TRIGGER GITHUB WORKFLOW
+=======================
+
+Script: scripts/github/trigger_workflow.py
+
+Requirements:
+- GitHub personal access token (GITHUB_TOKEN)
+- Repository with configured workflows
+
+Enter workflow name (e.g., deploy.yml):
+```
+
+---
+
+## PHASE 2: Post-Execution
+
+After script completes successfully:
+
+```
+✅ SCRIPT COMPLETED SUCCESSFULLY
+
+Results:
+[Show relevant output summary]
+
+What would you like to do next?
+
+1. Run another script
+2. View generated files
+3. Continue with other tasks
+```
+
+---
+
+## ERROR HANDLING
+
+Common errors and solutions:
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Azure CLI not found" | CLI not installed | Install from https://aka.ms/installazurecli |
+| "Token expired" | Session timeout | Run `az login` to re-authenticate |
+| "Workspace not found" | Wrong WORKSPACE_ID | Verify ID in Fabric portal URL |
+| "Model not found" | Wrong MODEL_ID | Check model exists in workspace |
+| "Permission denied" | Insufficient access | Request Contributor role on workspace |
+| "Connection timeout" | Network issues | Check VPN, firewall, or retry |
+
+**Debug mode:**
+```bash
+# Run with verbose output
+python scripts/tools/diagnose_fabric_connection.py --verbose
+```
+
+---
+
+## CONFIGURATION
+
+Scripts read configuration from `scripts/config/fabric_config.py`:
+
+```python
+# Required settings
+WORKSPACE_ID = "your-workspace-id"
+MODEL_ID = "your-model-id"
+
+# Optional settings
+TIMEOUT = 300  # seconds
+VERBOSE = False
+```
+
+**Finding your IDs:**
+
+1. Open Fabric portal (app.fabric.microsoft.com)
+2. Navigate to your workspace
+3. Workspace ID is in the URL: `/groups/[WORKSPACE_ID]/`
+4. Open the semantic model
+5. Model ID is in the URL: `/datasets/[MODEL_ID]/`
+
+---
+
+## Complexity Adaptation
+
+Adjust depth based on `config.json → experienceLevel`:
+- **beginner**: Step-by-step with explanations, reference library examples
+- **intermediate**: Standard depth, explain non-obvious decisions
+- **advanced**: Concise, skip basics, focus on edge cases and optimization
+
+---
+
+## Related Skills
+
+- `/deployment` — CI/CD and deployment pipelines
+- `/migration-assistant` — Migrate to Fabric
+- `/pbi-connect` — Connect to Fabric via MCP
+
+---
+
+## RELATED RESOURCES
+
+- [Power BI MCP Server](https://aka.ms/powerbi-modeling-mcp-vscode)
+- [Fabric REST API Documentation](https://learn.microsoft.com/fabric/admin/service-admin-portal)
+- [TMDL Reference](https://learn.microsoft.com/analysis-services/tmdl/tmdl-overview)