Implement non-blocking baseline packaging (Core + Steps.Common only)

[Copilot]

Summary

Ensures Import-Module IdLE succeeds on clean PowerShell 7 without RSAT, AD tools, or third-party dependencies. Only IdLE.Core and IdLE.Steps.Common are auto-imported; provider modules and optional step packs are shipped but require explicit import.

Motivation

Current auto-import includes system-dependent providers (AD, DirectorySync.EntraConnect) that block installation on non-Windows or environments without RSAT. This violates the "batteries included, non-blocking baseline" principle.

Type of Change

• Breaking change
• Refactoring / internal improvement
• Documentation update

Changes

Module manifest (baseline definition)

• src/IdLE/IdLE.psd1: Removed IdLE.Steps.DirectorySync, IdLE.Provider.AD, IdLE.Provider.DirectorySync.EntraConnect from NestedModules
• Baseline: IdLE.Core, IdLE.Steps.Common (auto-imported)
• Optional: All provider modules, IdLE.Steps.DirectorySync, IdLE.Steps.Mailbox (shipped, not auto-imported)

Core engine (nested module resolution)

• src/IdLE.Core/Public/Invoke-IdlePlanObject.ps1: Fixed Resolve-IdleStepHandler to resolve module-qualified commands (e.g., IdLE.Steps.Common\Invoke-IdleStepEmitEvent) from nested modules
• Previous: Get-Command -Name "Module\Command" failed for nested modules
• Fixed: Extract module/command, lookup via Get-Module -All, retrieve from ExportedCommands

Documentation

• docs/getting-started/installation.md: Non-blocking guarantee, baseline vs optional modules policy
• docs/advanced/releases.md: Reference link to installation guide for baseline policy (moved from inline documentation to avoid duplication)

Tests

• tests/ModuleSurface.Tests.ps1: Refactored baseline validation test with maintainable structure:
  • Abstracted baseline modules into single array $baselineModules for easy extension
  • Used foreach loop to validate each baseline module is auto-imported
  • Dynamic count check using $baselineModules.Count instead of hardcoded value
  • Pattern matching (^IdLE\.(Provider\.|Steps\.(?!Common$))) to detect any optional modules
  • Test cleanup strategy maintains isolation (only removes baseline modules to avoid breaking other tests)

Examples

• examples/Invoke-IdleDemo.ps1: Remove redundant IdLE.Steps.Common import (now baseline)

Testing

• Unit tests (318 passed, 1 skipped)
• Contract tests (provider contracts)
• Manual testing (all mock workflows, packaged module import)

How to test & review

Baseline import (no dependencies required):

Import-Module ./src/IdLE/IdLE.psd1
(Get-Module IdLE).NestedModules.Name  # Should show only: IdLE.Core, IdLE.Steps.Common

Workflow execution (with optional Mock provider):

Import-Module ./src/IdLE/IdLE.psd1
Import-Module ./src/IdLE.Provider.Mock/IdLE.Provider.Mock.psd1
# Execute workflow - built-in steps resolve via module-qualified names

Packaged artifact:

pwsh -File ./tools/New-IdleModulePackage.ps1 -Clean
tree artifacts/IdLE  # Shows Modules/IdLE.Core, Modules/IdLE.Steps.Common

Test abstraction and maintainability:

# The baseline test uses a single array to define baseline modules
# New baseline modules only need to be added to $baselineModules array
# Pattern matching automatically detects any optional modules
pwsh -File ./tools/Invoke-IdlePesterTests.ps1 -TestPath ./tests/ModuleSurface.Tests.ps1

Checklist

• Code follows STYLEGUIDE.md
• Tests added or updated
• Documentation updated
• No UI/auth logic added to IdLE.Core
• No breaking changes without discussion (breaking change acknowledged in issue)

Related Issues

Per issue instructions, this implements the non-blocking baseline without backward compatibility warnings.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Non-blocking batteries included baseline for packaging</issue_title>
<issue_description>## Problem Statement

We want to publish a single IdLE package to PowerShell Gallery, while ensuring:

• Install-Module IdLE + Import-Module IdLE is always non-blocking
• system-/tool-dependent providers can still be shipped, but must not break the baseline experience
• the staged package layout behaves the same as the repository src/ layout (“source vs packaged parity”)

Current state shows inconsistencies between:

• what IdLE auto-loads via NestedModules (integration modules), and
• what the packaging script stages (Core + Steps only), and
• what docs communicate about the “baseline” and shipped modules.

Proposed Solution (Decisions)

A) Publishing model

• We will publish only one PowerShell Gallery module/package: IdLE.
• The IdLE package may contain additional shipped modules (steps/providers) that are not automatically imported.

B) Import / module-loading policy (baseline vs optional)

Baseline (auto-imported by IdLE)

• IdLE (meta)
• IdLE.Core
• IdLE.Steps.Common

Optional (shipped, but not auto-imported)

• Provider modules and any other modules that may be system-/tool-dependent (e.g. RSAT, PSRemoting configuration, OS-specific features).
• Dev/Test/Example helper modules (not required for baseline runtime).

Hard rule

• Import-Module IdLE must remain non-blocking. Optional modules must never be required to import the baseline.

C) Provider dependency policy (no implicit third-party loading)

• Provider modules must not auto-install or auto-load third-party dependencies at import time.
• No #Requires -Modules <ThirdParty> and no top-level Import-Module <ThirdParty> that can block.
• Providers must validate prerequisites at execution time and fail fast with actionable remediation hints.

D) Mock provider policy

• IdLE.Provider.Mock should be shipped (supports examples and developer workflows),
  but not auto-imported by IdLE.
• Examples (and dev tooling) are responsible for importing it explicitly when needed.

Scope adjustment (split)

The documentation needs a clear, single-source definition of the above rules, with deduplication and structure review.
To avoid growing #97 beyond its packaging/loader scope:

• Non-blocking batteries included baseline for packaging #97 will focus on packaging + nested module staging + loader behavior to implement the decisions above.
• Documentation consolidation and “single-source of truth” work will be tracked in a new dedicated docs issue (to be created).
• Non-blocking batteries included baseline for packaging #97 will reference the docs issue as a dependency for final wording, but can still implement the technical behavior.

Impact

• Breaking change risk: Low-to-medium. Auto-import behavior changes for shipped modules.
• User experience: Improved stability. Baseline import always succeeds; missing prerequisites surface at execution time with clear remediation.
• Developer experience: Clear contract for provider authors (no import-time hard dependencies; prerequisite checks at execution).

Acceptance Criteria

1. Import-Module IdLE succeeds on a clean PowerShell 7 environment without RSAT/AD tools and without optional provider prerequisites.

• Importing IdLE only auto-imports succeeding IdLE.Core and IdLE.Steps.Common
• No further submodules are imported automatically

3. The staged PSGallery artifact contains the baseline modules and ships optional modules without importing them automatically.
4. Source layout and packaged layout behave consistently for module resolution.
5. Provider modules do not block on import due to third-party dependencies (validated by tests / lint rules where feasible).
6. Clear error messages for missing prerequisites occur at execution time, not import time.
7. All docs and examples are updated accordingly and describe consistently the desired behavior
8. Tests are updated / there is a test to ensure the wanted auto-import behavior

Definition of Done

• All acceptance criteria met
• Pester green
• PSScriptAnalyzer green
• Git status clean
• Docs updated where needed
• Examples updated where needed</issue_description>

<agent_instructions>no backward compatibility documentation, references, warnings or hints needed - although mentioned in documentation! We assume there was no "Before" state as I am the only one newing</agent_instructions>

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

• Fixes Non-blocking batteries included baseline for packaging #97

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[blindzero]

@copilot do we have to change anything in the tests in general to make sure the required stuff is imported (e.g. mock, ...)?

[Copilot]

@copilot do we have to change anything in the tests in general to make sure the required stuff is imported (e.g. mock, ...)?

No changes needed in tests. The test helper (Import-IdleTestModule) already explicitly imports optional modules like Mock and DirectorySync that tests depend on. With the baseline changes, IdLE.Steps.Common is now auto-imported when you import IdLE, but the explicit import in the test helper is harmless (idempotent) and ensures backward compatibility. Tests continue to work as before.

[Copilot]

Pull request overview

This PR implements a non-blocking baseline packaging strategy for IdLE, ensuring Import-Module IdLE succeeds on any clean PowerShell 7 environment without external dependencies. Only IdLE.Core and IdLE.Steps.Common are auto-imported as the baseline; all provider modules and optional step packs are shipped but require explicit import.

Changes:

• Reduced auto-imported nested modules to baseline only (Core + Steps.Common)
• Enhanced core engine to resolve module-qualified commands from nested modules
• Added comprehensive test validation for baseline-only auto-import behavior with maintainable pattern matching
• Updated documentation to clearly define baseline vs optional modules policy
• Updated examples to reflect explicit import requirement for optional modules

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/IdLE/IdLE.psd1	Reduced NestedModules to baseline only (Core, Steps.Common); removed optional provider and step modules
src/IdLE.Core/Public/Invoke-IdlePlanObject.ps1	Enhanced module-qualified command resolution to support nested modules using Get-Module -All and ExportedCommands lookup
tests/ModuleSurface.Tests.ps1	Added comprehensive test with maintainable structure validating baseline-only auto-import using regex pattern matching
examples/Invoke-IdleDemo.ps1	Removed redundant Steps.Common import (now baseline); clarified Mock provider requires explicit import
docs/getting-started/installation.md	Documented non-blocking guarantee, baseline vs optional modules policy, and explicit import pattern
docs/advanced/releases.md	Referenced installation guide for baseline policy to avoid duplication