EXO provider: fail-fast prerequisites check, lazy re-check on each operation, and docs update

[Copilot]

• Explore repository structure and understand existing code
• Enhance Test-IdleExchangeOnlinePrerequisites: 3-layer check (module installed, imported, session active)
• Add Write-Verbose diagnostic events during provider initialization
• Add 7 unit tests for enhanced prerequisites check
• Update provider-exchangeonline.md docs: summary table, token requirements, troubleshooting entries
• Address review feedback: use Get-Mailbox as active session indicator
• Address review feedback: revert adapter back to Get-Mailbox
• Address review feedback: make prerequisites check lazy (re-check on each operation, not cached)
• Fix MDX parse error: move app-only auth code example out of blockquote to avoid JSX tag parsing of <thumbprint> etc.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>EXO - ExchangeOnline provider prerequisites unclear (token scopes/audience) + missing one-time cmdlet availability sanity check</issue_title>
<issue_description>## Description

ExchangeOnline provider usage fails with non-actionable errors (for example Get-Mailbox not recognized) because IdLE assumes an authenticated Exchange Online PowerShell session already exists in the same process/runspace. Documentation currently does not clearly explain the required EXO delegated permissions/scopes and token audience requirements, and the provider does not perform a one-time sanity check to fail fast with actionable guidance.

This issue will NOT add Connect-ExchangeOnline into the provider (authentication remains an external prerequisite, consistent with Entra provider usage). The fix is documentation + a one-time sanity check + (if needed) aligning steps to supported EXO cmdlets.

Steps to Reproduce

1. Prepare an EXO token and/or import ExchangeOnlineManagement, but do not establish an EXO session that exposes Get-Mailbox (only Get-EXOMailbox exists).
2. Run a workflow/step that uses the ExchangeOnline provider (e.g., mailbox type/permissions steps).
3. Observe nested exceptions, ending in The term 'Get-Mailbox' is not recognized....

Expected Behavior

• IdLE fails fast with a clear message if prerequisites are missing:
  • EXO session must be established outside IdLE (same process/runspace).
  • Token must be minted for https://outlook.office365.com with required delegated permissions (e.g., Exchange.Manage / Exchange.ManageV2).
  • Required cmdlets (Get-EXOMailbox, etc.) must be available.
• Provider docs (template-conform) clearly describe how to obtain a valid delegated EXO token using MSAL.PS (https://outlook.office365.com/.default) and what must appear in scp.

Actual Behavior

• Steps fail late and non-actionably, e.g.:
  • Exchange Online command 'Get-Mailbox' failed | The term 'Get-Mailbox' is not recognized...
• Users cannot easily determine whether:
  • the EXO module is imported,
  • a session is established,
  • the token is valid for EXO.

Environment

• PowerShell version: 7.x (IdLE minimum)
• OS: (fill in)
• IdLE version / commit: (fill in)
• Execution context (CLI / Service / CI): (fill in)

Additional Context

Implementation scope (agent-safe, no open questions)

1. One-time sanity check (per provider instance)

• Add a private Ensure-IdleExchangeOnlinePrerequisites (name aligned to repo conventions) that runs once per provider instance (cache state).
• Validates:
  • ExchangeOnlineManagement is importable.
  • Required cmdlets are available:
    • Prefer Get-EXOMailbox / Set-EXOMailbox where applicable.
    • If any IdLE step still requires Get-Mailbox, either migrate the step to Get-EXOMailbox or fail with an actionable message explaining why Get-Mailbox is missing.

2. Diagnostics (IdLE events)
   Emit structured events (no secrets/tokens) during initialization:

• Provider.ExchangeOnline.Init.Start
• Provider.ExchangeOnline.Prerequisites.ModuleImport.(Success|Failure)
• Provider.ExchangeOnline.CommandAvailability (flags for Get-EXOMailbox, Get-Mailbox, etc.)
• Provider.ExchangeOnline.Init.End

3. Documentation (must follow provider docs template)
   Update docs/reference/providers/provider-exchangeonline.md strictly according to the provider docs template, including:

• Clear prerequisites: IdLE does not run Connect-ExchangeOnline automatically.
• Token requirements for delegated user:
  • Use Get-MsalToken ... -Scopes "https://outlook.office365.com/.default" -DeviceCode
  • Token must contain scp entries including https://outlook.office365.com/Exchange.Manage and/or Exchange.ManageV2 (depending on required operations).
  • Explain .default behavior for this resource.
• Troubleshooting for:
  • Get-EXOMailbox exists, Get-Mailbox missing
  • Unauthorized when -AccessToken is used (missing delegated EXO permissions / wrong token)

4. Tests

• Unit tests for the one-time sanity check:
  • module import failure -> actionable error
  • cmdlets missing -> actionable error
  • cmdlets present -> pass and cache state
• Update step tests if cmdlet usage changes.

</issue_description>

<agent_instructions>check this issue against issue #232 as we want to change the structure of provider documentation with #232 in general</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes EXO - ExchangeOnline provider prerequisites unclear (token scopes/audience) + missing one-time cmdlet availability sanity check #229

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b7a2531f03

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR improves the Exchange Online provider’s usability by adding a fail-fast prerequisites check (with actionable guidance), caching the result per provider instance, and restructuring/updating the provider documentation to match the newer template direction (issue #232).

Changes:

• Adds Test-IdleExchangeOnlinePrerequisites with layered checks (module installed, module imported, EXO session established) and actionable notes.
• Caches prerequisites results on the provider instance and emits structured verbose diagnostics during provider initialization.
• Adds Pester unit tests for the prerequisites function and updates the provider reference documentation with clearer auth/troubleshooting guidance.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
tests/Providers/ExchangeOnlineProvider.Tests.ps1	Adds unit tests validating the new prerequisites check behavior and result shape.
src/IdLE.Provider.ExchangeOnline/Public/New-IdleExchangeOnlineProvider.ps1	Runs prerequisites check at construction, emits verbose diagnostics, and uses a cached result for later operations.
src/IdLE.Provider.ExchangeOnline/Private/Test-IdleExchangeOnlinePrerequisites.ps1	Implements the new structured prerequisites check (module + cmdlet/session availability).
docs/reference/providers/provider-exchangeonline.md	Restructures provider docs and expands authentication + troubleshooting guidance.

[github-actions]

Code Coverage Report

Overall Project	73.57%	🍏

There is no coverage information present for the Files changed

[blindzero]

@copilot our Docs Consistency Checker found an MDX issue: MDX risks (possible accidental MDX parsing)

• docs/reference/providers/provider-exchangeonline.md:126 [JSXTag] > Connect-ExchangeOnline -CertificateThumbprint '' -AppId '' -Organization '.onmicrosoft.com'

[Copilot]

@copilot our Docs Consistency Checker found an MDX issue: MDX risks (possible accidental MDX parsing)

• docs/reference/providers/provide...

Fixed in 4f74dd6 — moved the app-only auth code example out of the blockquote and into a standalone fenced code block, so the <thumbprint>, <app-id>, and <tenant> placeholders are no longer parsed as JSX tags.