devskill 2.0.7 → 2.0.8

package/skills/azure-deployment-preflight/references/REPORT-TEMPLATE.md

@@ -0,0 +1,352 @@
+# Preflight Report Template
+
+Use this template structure when generating `preflight-report.md` in the project root.
+
+---
+
+## Template
+
+```markdown
+# Azure Deployment Preflight Report
+
+**Generated:** {timestamp}
+**Status:** {overall-status}
+
+---
+
+## Summary
+
+| Property | Value |
+|----------|-------|
+| **Template File(s)** | {bicep-files} |
+| **Parameter File(s)** | {param-files-or-none} |
+| **Project Type** | {azd-project | standalone-bicep} |
+| **Deployment Scope** | {resourceGroup | subscription | managementGroup | tenant} |
+| **Target** | {resource-group-name | subscription-name | mg-id} |
+| **Validation Level** | {Provider | ProviderNoRbac} |
+
+### Validation Results
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Bicep Syntax | {✅ Pass | ❌ Fail | ⚠️ Warnings | ⏭️ Skipped} | {details} |
+| What-If Analysis | {✅ Pass | ❌ Fail | ⏭️ Skipped} | {details} |
+| Permission Check | {✅ Pass | ⚠️ Limited | ❌ Fail} | {details} |
+
+---
+
+## Tools Executed
+
+### Commands Run
+
+| Step | Command | Exit Code | Duration |
+|------|---------|-----------|----------|
+| 1 | `{command}` | {0 | non-zero} | {duration} |
+| 2 | `{command}` | {0 | non-zero} | {duration} |
+
+### Tool Versions
+
+| Tool | Version |
+|------|---------|
+| Azure CLI | {version} |
+| Bicep CLI | {version} |
+| Azure Developer CLI | {version-or-n/a} |
+
+---
+
+## Issues
+
+{if-no-issues}
+✅ **No issues found.** The deployment is ready to proceed.
+{end-if}
+
+{if-issues-exist}
+### Errors
+
+{for-each-error}
+#### ❌ {error-title}
+
+- **Severity:** Error
+- **Source:** {bicep-build | what-if | permissions}
+- **Location:** {file-path}:{line}:{column} (if applicable)
+- **Message:** {error-message}
+- **Remediation:** {suggested-fix}
+- **Documentation:** {link-if-available}
+
+{end-for-each}
+
+### Warnings
+
+{for-each-warning}
+#### ⚠️ {warning-title}
+
+- **Severity:** Warning
+- **Source:** {source}
+- **Message:** {warning-message}
+- **Recommendation:** {suggested-action}
+
+{end-for-each}
+{end-if}
+
+---
+
+## What-If Results
+
+{if-what-if-succeeded}
+
+### Change Summary
+
+| Change Type | Count |
+|-------------|-------|
+| 🆕 Create | {count} |
+| 📝 Modify | {count} |
+| 🗑️ Delete | {count} |
+| ✓ No Change | {count} |
+| ⚠️ Ignore | {count} |
+
+### Resources to Create
+
+{if-resources-to-create}
+| Resource Type | Resource Name |
+|---------------|---------------|
+| {type} | {name} |
+{end-if}
+
+{if-no-resources-to-create}
+*No resources will be created.*
+{end-if}
+
+### Resources to Modify
+
+{if-resources-to-modify}
+#### {resource-type}/{resource-name}
+
+| Property | Current Value | New Value |
+|----------|---------------|-----------|
+| {property-path} | {current} | {new} |
+
+{end-if}
+
+{if-no-resources-to-modify}
+*No resources will be modified.*
+{end-if}
+
+### Resources to Delete
+
+{if-resources-to-delete}
+| Resource Type | Resource Name |
+|---------------|---------------|
+| {type} | {name} |
+
+> ⚠️ **Warning:** Resources listed for deletion will be permanently removed.
+{end-if}
+
+{if-no-resources-to-delete}
+*No resources will be deleted.*
+{end-if}
+
+{end-if-what-if-succeeded}
+
+{if-what-if-failed}
+### What-If Analysis Failed
+
+The what-if operation could not complete. See the Issues section for details.
+{end-if}
+
+---
+
+## Recommendations
+
+{generate-based-on-findings}
+
+1. {recommendation-1}
+2. {recommendation-2}
+3. {recommendation-3}
+
+---
+
+## Next Steps
+
+{if-all-passed}
+The preflight validation passed. You can proceed with deployment:
+
+**For azd projects:**
+```bash
+azd provision
+# or
+azd up
+```
+
+**For standalone Bicep:**
+```bash
+az deployment group create \
+  --resource-group {rg-name} \
+  --template-file {bicep-file} \
+  --parameters {param-file}
+```
+{end-if}
+
+{if-issues-exist}
+Please resolve the issues listed above before deploying. After fixes:
+
+1. Re-run preflight validation to verify fixes
+2. Proceed with deployment once all checks pass
+{end-if}
+
+---
+
+*Report generated by Azure Deployment Preflight Skill*
+```
+
+---
+
+## Status Values
+
+### Overall Status
+
+| Status | Meaning | Visual |
+|--------|---------|--------|
+| **Pass** | All checks succeeded, safe to deploy | ✅ |
+| **Pass with Warnings** | Checks succeeded but review warnings | ⚠️ |
+| **Fail** | One or more checks failed | ❌ |
+
+### Individual Check Status
+
+| Status | Meaning |
+|--------|---------|
+| ✅ Pass | Check completed successfully |
+| ❌ Fail | Check found errors |
+| ⚠️ Warnings | Check passed with warnings |
+| ⏭️ Skipped | Check was skipped (tool unavailable, etc.) |
+
+---
+
+## Example Report
+
+```markdown
+# Azure Deployment Preflight Report
+
+**Generated:** 2026-01-16T14:32:00Z
+**Status:** ⚠️ Pass with Warnings
+
+---
+
+## Summary
+
+| Property | Value |
+|----------|-------|
+| **Template File(s)** | `infra/main.bicep` |
+| **Parameter File(s)** | `infra/main.bicepparam` |
+| **Project Type** | azd project |
+| **Deployment Scope** | subscription |
+| **Target** | my-subscription |
+| **Validation Level** | Provider |
+
+### Validation Results
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Bicep Syntax | ✅ Pass | No errors found |
+| What-If Analysis | ⚠️ Warnings | 1 resource ignored due to nested template limits |
+| Permission Check | ✅ Pass | Full deployment permissions verified |
+
+---
+
+## Tools Executed
+
+### Commands Run
+
+| Step | Command | Exit Code | Duration |
+|------|---------|-----------|----------|
+| 1 | `bicep build infra/main.bicep --stdout` | 0 | 1.2s |
+| 2 | `azd provision --preview --environment dev` | 0 | 8.4s |
+
+### Tool Versions
+
+| Tool | Version |
+|------|---------|
+| Azure CLI | 2.76.0 |
+| Bicep CLI | 0.25.3 |
+| Azure Developer CLI | 1.9.0 |
+
+---
+
+## Issues
+
+### Warnings
+
+#### ⚠️ Nested Template Limit Reached
+
+- **Severity:** Warning
+- **Source:** what-if
+- **Message:** 1 resource was ignored because nested template expansion limits were reached
+- **Recommendation:** Review the ignored resource manually after deployment
+
+---
+
+## What-If Results
+
+### Change Summary
+
+| Change Type | Count |
+|-------------|-------|
+| 🆕 Create | 3 |
+| 📝 Modify | 1 |
+| 🗑️ Delete | 0 |
+| ✓ No Change | 2 |
+| ⚠️ Ignore | 1 |
+
+### Resources to Create
+
+| Resource Type | Resource Name |
+|---------------|---------------|
+| Microsoft.Resources/resourceGroups | rg-myapp-dev |
+| Microsoft.Storage/storageAccounts | stmyappdev |
+| Microsoft.Web/sites | app-myapp-dev |
+
+### Resources to Modify
+
+#### Microsoft.KeyVault/vaults/kv-myapp-dev
+
+| Property | Current Value | New Value |
+|----------|---------------|-----------|
+| properties.sku.name | standard | premium |
+| tags.environment | staging | dev |
+
+### Resources to Delete
+
+*No resources will be deleted.*
+
+---
+
+## Recommendations
+
+1. Review the storage account name `stmyappdev` to ensure it meets naming requirements
+2. Confirm the Key Vault SKU upgrade from standard to premium is intentional
+3. The ignored nested template resource should be verified after deployment
+
+---
+
+## Next Steps
+
+The preflight validation passed with warnings. Review the warnings above, then proceed:
+
+```bash
+azd provision --environment dev
+```
+
+---
+
+*Report generated by Azure Deployment Preflight Skill*
+```
+
+---
+
+## Formatting Guidelines
+
+1. **Use consistent emoji** for visual scanning
+2. **Include line numbers** when referencing Bicep errors
+3. **Provide actionable remediation** for each issue
+4. **Link to documentation** when available
+5. **Order issues by severity** (errors first, then warnings)
+6. **Include command examples** in Next Steps

package/skills/azure-deployment-preflight/references/VALIDATION-COMMANDS.md

@@ -0,0 +1,379 @@
+# Validation Commands Reference
+
+This reference documents all commands used for Azure deployment preflight validation.
+
+## Azure Developer CLI (azd)
+
+### azd provision --preview
+
+Preview infrastructure changes for azd projects without deploying.
+
+```bash
+azd provision --preview [options]
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--environment`, `-e` | Name of the environment to use |
+| `--no-prompt` | Accept defaults without prompting |
+| `--debug` | Enable debug logging |
+| `--cwd` | Set working directory |
+
+**Examples:**
+
+```bash
+# Preview with default environment
+azd provision --preview
+
+# Preview specific environment
+azd provision --preview --environment dev
+
+# Preview without prompts (CI/CD)
+azd provision --preview --no-prompt
+```
+
+**Output:** Shows resources that will be created, modified, or deleted.
+
+### azd auth login
+
+Authenticate to Azure for azd operations.
+
+```bash
+azd auth login [options]
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--check-status` | Check login status without logging in |
+| `--use-device-code` | Use device code flow |
+| `--tenant-id` | Specify tenant |
+| `--client-id` | Service principal client ID |
+
+### azd env list
+
+List available environments.
+
+```bash
+azd env list
+```
+
+---
+
+## Azure CLI (az)
+
+### az deployment group what-if
+
+Preview changes for resource group deployments.
+
+```bash
+az deployment group what-if \
+  --resource-group <rg-name> \
+  --template-file <bicep-file> \
+  [options]
+```
+
+**Required Parameters:**
+| Parameter | Description |
+|-----------|-------------|
+| `--resource-group`, `-g` | Target resource group name |
+| `--template-file`, `-f` | Path to Bicep file |
+
+**Optional Parameters:**
+| Parameter | Description |
+|-----------|-------------|
+| `--parameters`, `-p` | Parameter file or inline values |
+| `--validation-level` | `Provider` (default), `ProviderNoRbac`, or `Template` |
+| `--result-format` | `FullResourcePayloads` (default) or `ResourceIdOnly` |
+| `--no-pretty-print` | Output raw JSON for parsing |
+| `--name`, `-n` | Deployment name |
+| `--exclude-change-types` | Exclude specific change types from output |
+
+**Validation Levels:**
+| Level | Description | Use Case |
+|-------|-------------|----------|
+| `Provider` | Full validation with RBAC checks | Default, most thorough |
+| `ProviderNoRbac` | Full validation, read permissions only | When lacking deploy permissions |
+| `Template` | Static syntax validation only | Quick syntax check |
+
+**Examples:**
+
+```bash
+# Basic what-if
+az deployment group what-if \
+  --resource-group my-rg \
+  --template-file main.bicep
+
+# With parameters and full validation
+az deployment group what-if \
+  --resource-group my-rg \
+  --template-file main.bicep \
+  --parameters main.bicepparam \
+  --validation-level Provider
+
+# Fallback without RBAC checks
+az deployment group what-if \
+  --resource-group my-rg \
+  --template-file main.bicep \
+  --validation-level ProviderNoRbac
+
+# JSON output for parsing
+az deployment group what-if \
+  --resource-group my-rg \
+  --template-file main.bicep \
+  --no-pretty-print
+```
+
+### az deployment sub what-if
+
+Preview changes for subscription-level deployments.
+
+```bash
+az deployment sub what-if \
+  --location <location> \
+  --template-file <bicep-file> \
+  [options]
+```
+
+**Required Parameters:**
+| Parameter | Description |
+|-----------|-------------|
+| `--location`, `-l` | Location for deployment metadata |
+| `--template-file`, `-f` | Path to Bicep file |
+
+**Examples:**
+
+```bash
+az deployment sub what-if \
+  --location eastus \
+  --template-file main.bicep \
+  --parameters main.bicepparam \
+  --validation-level Provider
+```
+
+### az deployment mg what-if
+
+Preview changes for management group deployments.
+
+```bash
+az deployment mg what-if \
+  --location <location> \
+  --management-group-id <mg-id> \
+  --template-file <bicep-file> \
+  [options]
+```
+
+**Required Parameters:**
+| Parameter | Description |
+|-----------|-------------|
+| `--location`, `-l` | Location for deployment metadata |
+| `--management-group-id`, `-m` | Target management group ID |
+| `--template-file`, `-f` | Path to Bicep file |
+
+### az deployment tenant what-if
+
+Preview changes for tenant-level deployments.
+
+```bash
+az deployment tenant what-if \
+  --location <location> \
+  --template-file <bicep-file> \
+  [options]
+```
+
+**Required Parameters:**
+| Parameter | Description |
+|-----------|-------------|
+| `--location`, `-l` | Location for deployment metadata |
+| `--template-file`, `-f` | Path to Bicep file |
+
+### az login
+
+Authenticate to Azure CLI.
+
+```bash
+az login [options]
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--tenant`, `-t` | Tenant ID or domain |
+| `--use-device-code` | Use device code flow |
+| `--service-principal` | Login as service principal |
+
+### az account show
+
+Display current subscription context.
+
+```bash
+az account show
+```
+
+### az group exists
+
+Check if resource group exists.
+
+```bash
+az group exists --name <rg-name>
+```
+
+---
+
+## Bicep CLI
+
+### bicep build
+
+Compile Bicep to ARM JSON and validate syntax.
+
+```bash
+bicep build <bicep-file> [options]
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--stdout` | Output to stdout instead of file |
+| `--outdir` | Output directory |
+| `--outfile` | Output file path |
+| `--no-restore` | Skip module restore |
+
+**Examples:**
+
+```bash
+# Validate syntax (output to stdout, no file created)
+bicep build main.bicep --stdout > /dev/null
+
+# Build to specific directory
+bicep build main.bicep --outdir ./build
+
+# Validate multiple files
+for f in *.bicep; do bicep build "$f" --stdout; done
+```
+
+**Error Output Format:**
+```
+/path/to/file.bicep(22,51) : Error BCP064: Found unexpected tokens in interpolated expression.
+/path/to/file.bicep(22,51) : Error BCP004: The string at this location is not terminated.
+```
+
+Format: `<file>(<line>,<column>) : <severity> <code>: <message>`
+
+### bicep --version
+
+Check Bicep CLI version.
+
+```bash
+bicep --version
+```
+
+---
+
+## Parameter File Detection
+
+### Bicep Parameters (.bicepparam)
+
+Modern Bicep parameter files (recommended):
+
+```bicep
+using './main.bicep'
+
+param location = 'eastus'
+param environment = 'dev'
+param tags = {
+  environment: 'dev'
+  project: 'myapp'
+}
+```
+
+**Detection pattern:** `<template-name>.bicepparam`
+
+### JSON Parameters (.parameters.json)
+
+Traditional ARM parameter files:
+
+```json
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "location": { "value": "eastus" },
+    "environment": { "value": "dev" }
+  }
+}
+```
+
+**Detection patterns:**
+- `<template-name>.parameters.json`
+- `parameters.json`
+- `parameters/<env>.json`
+
+### Using Parameters with Commands
+
+```bash
+# Bicep parameters file
+az deployment group what-if \
+  --resource-group my-rg \
+  --template-file main.bicep \
+  --parameters main.bicepparam
+
+# JSON parameters file
+az deployment group what-if \
+  --resource-group my-rg \
+  --template-file main.bicep \
+  --parameters @parameters.json
+
+# Inline parameter overrides
+az deployment group what-if \
+  --resource-group my-rg \
+  --template-file main.bicep \
+  --parameters main.bicepparam \
+  --parameters location=westus
+```
+
+---
+
+## Determining Deployment Scope
+
+Check the Bicep file's `targetScope` declaration:
+
+```bicep
+// Resource Group (default if not specified)
+targetScope = 'resourceGroup'
+
+// Subscription
+targetScope = 'subscription'
+
+// Management Group
+targetScope = 'managementGroup'
+
+// Tenant
+targetScope = 'tenant'
+```
+
+**Scope to Command Mapping:**
+
+| targetScope | Command | Required Parameters |
+|-------------|---------|---------------------|
+| `resourceGroup` | `az deployment group what-if` | `--resource-group` |
+| `subscription` | `az deployment sub what-if` | `--location` |
+| `managementGroup` | `az deployment mg what-if` | `--location`, `--management-group-id` |
+| `tenant` | `az deployment tenant what-if` | `--location` |
+
+---
+
+## Version Requirements
+
+| Tool | Minimum Version | Recommended Version | Key Features |
+|------|-----------------|---------------------|--------------|
+| Azure CLI | 2.14.0 | 2.76.0+ | `--validation-level` switch |
+| Azure Developer CLI | 1.0.0 | Latest | `--preview` flag |
+| Bicep CLI | 0.4.0 | Latest | Best error messages |
+
+**Check versions:**
+```bash
+az --version
+azd version
+bicep --version
+```