1<#
2.SYNOPSIS
3    Verifies the local environment for creating a hosted Foundry agent with `azd ai`.
4.DESCRIPTION
5    Runs all the read-only checks in one pass and prints a single concise summary,
6    so the agent does not have to run (and reason over) each azd command separately.
7 
8    Output lines are prefixed with [OK], [WARN], or [ACTION].
9    Exit code is 0 when no blocking actions remain, 1 when at least one [ACTION] is required.
10.EXAMPLE
11    ./verify-environment.ps1
12#>
13 
14$ErrorActionPreference = "Stop"
15$actionRequired = $false
16 
17function Note-Ok     { param([string]$m) Write-Output "[OK] $m" }
18function Note-Warn   { param([string]$m) Write-Output "[WARN] $m" }
19function Note-Action { param([string]$m) Write-Output "[ACTION] $m"; $script:actionRequired = $true }
20 
21function Get-AzdJson {
22    param([string[]]$AzdArgs)
23    try {
24        $raw = & azd @AzdArgs 2>$null
25        if (-not $raw) { return $null }
26        return ($raw | ConvertFrom-Json -ErrorAction Stop)
27    } catch {
28        return $null
29    }
30}
31 
32# Refresh PATH to pick up recently-installed tools (e.g. azd installed in same session)
33$env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "User")
34 
35function Add-CommandFallbackPath {
36    param(
37        [string] $CommandName,
38        [string[]] $Directories
39    )
40 
41    if (Get-Command $CommandName -ErrorAction SilentlyContinue) {
42        return [pscustomobject]@{ Found = $true; AddedPath = $null }
43    }
44 
45    foreach ($dir in $Directories) {
46        if (-not $dir) { continue }
47        foreach ($ext in @(".exe", ".cmd", ".bat")) {
48            $candidate = Join-Path $dir "$CommandName$ext"
49            if (Test-Path $candidate) {
50                $env:Path = "$dir;$env:Path"
51                return [pscustomobject]@{ Found = $true; AddedPath = $dir }
52            }
53        }
54    }
55 
56    return [pscustomobject]@{ Found = [bool](Get-Command $CommandName -ErrorAction SilentlyContinue); AddedPath = $null }
57}
58 
59function Test-AzdAuthLoggedIn {
60    $raw = ""
61    try {
62        $raw = (& azd auth login --check-status 2>&1) -join "`n"
63    } catch {
64        $raw = $_ | Out-String
65    }
66    $authExit = $LASTEXITCODE
67 
68    if ($raw -match "(?i)(not\s+logged\s+in|not\s+authenticated|no\s+account|login\s+required|please\s+run.*azd\s+auth\s+login|run.*azd\s+auth\s+login|expired)") {
69        return $false
70    }
71 
72    if ($raw -match "(?i)(logged\s+in|authenticated|already\s+logged\s+in)") {
73        return $true
74    }
75 
76    # Unrecognized output -- fall back to exit code
77    return ($authExit -eq 0)
78}
79 
80# 1. Required CLIs
81# Check PATH first, then probe common install locations (winget, MSI, chocolatey)
82$azdCommand = Add-CommandFallbackPath "azd" @(
83    "$env:LOCALAPPDATA\Programs\Azure Dev CLI",
84    "$env:ProgramFiles\Azure Dev CLI",
85    "${env:ProgramFiles(x86)}\Azure Dev CLI",
86    "$env:USERPROFILE\.azd\bin"
87)
88$azdInstalled = $azdCommand.Found
89if ($azdCommand.AddedPath) {
90    Note-Warn "azd found at '$($azdCommand.AddedPath)' but was not on PATH. Added automatically for this session."
91}
92if (-not $azdInstalled) {
93    Note-Action "Azure Developer CLI (azd) is not installed. Install it from https://aka.ms/azd-install, then re-run."
94}
95 
96$azCommand = Add-CommandFallbackPath "az" @(
97    "$env:ProgramFiles\Microsoft SDKs\Azure\CLI2\wbin",
98    "${env:ProgramFiles(x86)}\Microsoft SDKs\Azure\CLI2\wbin"
99)
100$azInstalled = $azCommand.Found
101if ($azCommand.AddedPath) {
102    Note-Warn "az found at '$($azCommand.AddedPath)' but was not on PATH. Added automatically for this session."
103}
104if (-not $azInstalled) {
105    Note-Action "Azure CLI (az) is not installed. Install it from https://aka.ms/installazurecli, then re-run."
106}
107 
108if (-not $azdInstalled -or -not $azInstalled) {
109    Write-Output ""
110    Write-Output "Summary: CLI missing -- cannot continue."
111    exit 1
112}
113 
114$verJson = Get-AzdJson @("version", "--output", "json")
115$azdVersion = if ($verJson -and $verJson.azd -and $verJson.azd.version) { $verJson.azd.version } else { "unknown" }
116Note-Ok "azd installed (version $azdVersion)."
117 
118try {
119    $azVersionRaw = (& az version --query '"azure-cli"' -o tsv 2>$null) -join "`n"
120} catch {
121    $azVersionRaw = ""
122}
123$azVersion = if ($azVersionRaw) { $azVersionRaw.Trim() } else { "unknown" }
124Note-Ok "Azure CLI installed (version $azVersion)."
125 
126# 2. Required azd extensions
127try {
128    $extRaw = (& azd extension list --output json 2>$null) -join "`n"
129} catch {
130    $extRaw = ""
131}
132foreach ($ext in @("azure.ai.agents", "azure.ai.projects")) {
133    if ($extRaw -match [regex]::Escape($ext)) {
134        Note-Ok "Extension '$ext' is installed."
135    } else {
136        Note-Action "Extension '$ext' is missing. Run: azd extension install $ext"
137    }
138}
139 
140# 3. Auth status
141if (Test-AzdAuthLoggedIn) {
142    Note-Ok "Logged in to azd."
143} else {
144    Note-Action "Not logged in to azd. Ask the user to run 'azd auth login' (it opens a browser; never run it for them)."
145}
146 
147try {
148    $azAccountRaw = (& az account show --output json 2>$null) -join "`n"
149} catch {
150    $azAccountRaw = ""
151}
152if (-not $azAccountRaw) {
153    Note-Action "Not logged in to Azure CLI. Ask the user to run 'az login' (it opens a browser; never run it for them)."
154} else {
155    try {
156        $azAccount = $azAccountRaw | ConvertFrom-Json -ErrorAction Stop
157        $state = if ($azAccount.PSObject.Properties.Name -contains "state") { $azAccount.state } else { "" }
158        if ($state -and $state -ne "Enabled") {
159            Note-Action "Azure CLI active subscription state is '$state'. Ask the user to select an enabled subscription with 'az account set --subscription <id>'."
160        } else {
161            $subName = if ($azAccount.PSObject.Properties.Name -contains "name" -and $azAccount.name) { $azAccount.name } else { "unknown" }
162            Note-Ok "Azure CLI logged in (subscription: $subName)."
163        }
164    } catch {
165        Note-Action "Unable to verify Azure CLI login status. Ask the user to run 'az login' and re-run this script."
166    }
167}
168 
169if ($actionRequired) {
170    Write-Output ""
171    Write-Output "Summary: action required -- resolve the [ACTION] items above before continuing."
172    exit 1
173}
174 
175# 4. Foundry project endpoint (optional at this stage)
176# Short-circuit when there's no azd project in cwd: `azd ai project show` / `agent show`
177# would just return nothing after a ~3s subprocess each.
178if (-not (Test-Path "azure.yaml")) {
179    Note-Warn "No Foundry project endpoint set yet. A new project will be created at provision/deploy time, or supply an existing project resource ID."
180    Note-Ok "No agent deployed yet. Proceed with create."
181} else {
182    $projectJson = Get-AzdJson @("ai", "project", "show", "--output", "json")
183    $endpoint = $null
184    if ($projectJson) {
185        foreach ($k in @("endpoint", "projectEndpoint", "aiProjectEndpoint")) {
186            if ($projectJson.PSObject.Properties.Name -contains $k -and $projectJson.$k) {
187                $endpoint = $projectJson.$k
188                break
189            }
190        }
191    }
192    if ($endpoint) {
193        Note-Ok "Foundry project endpoint configured: $endpoint"
194    } else {
195        Note-Warn "No Foundry project endpoint set yet. A new project will be created at provision/deploy time, or supply an existing project resource ID."
196    }
197 
198    # 5. Agent deployment status
199    $agentJson = Get-AzdJson @("ai", "agent", "show", "--output", "json")
200    if ($agentJson) {
201        $status = if ($agentJson.PSObject.Properties.Name -contains "status" -and $agentJson.status) { $agentJson.status } else { "unknown" }
202        switch ($status) {
203            { $_ -in @("active", "deployed") } { Note-Ok "An agent is already deployed (status: $status). Skip to deploy.md to redeploy, or tools to add a tool." }
204            "not_deployed"                     { Note-Ok "No agent deployed yet (status: not_deployed). Proceed with create." }
205            default                            { Note-Warn "Agent status: $status." }
206        }
207    } else {
208        Note-Ok "No agent deployed yet. Proceed with create."
209    }
210}
211 
212Write-Output ""
213if ($actionRequired) {
214    Write-Output "Summary: action required -- resolve the [ACTION] items above before continuing."
215    exit 1
216} else {
217    Write-Output "Summary: environment ready for 'azd ai' hosted-agent creation."
218    exit 0
219}
220