Move step infrastructure from IdLE.Steps.Common to IdLE.Core

[Copilot]

IdLE.Steps.Common mixed two concerns: generic step infrastructure (helpers, contracts) and step implementations. This made the layering unclear and forced step packs to depend on implementation libraries for foundational utilities.

Changes

IdLE.Core now exports step infrastructure:

• Invoke-IdleProviderMethod - provider method invocation with auth session support
• Test-IdleProviderMethodParameter - parameter inspection for backwards compatibility

Step packs now depend on IdLE.Core:

# Before
@{
    RequiredModules = @('IdLE.Steps.Common')
}

# After
@{
    RequiredModules = @('IdLE.Core', 'IdLE.Steps.Common')  # if reusing common steps
    # or
    RequiredModules = @('IdLE.Core')  # for pure custom step packs
}

Each step pack implements its own metadata catalog:

• IdLE.Steps.Common → metadata for common steps (EmitEvent, CreateIdentity, etc.)
• IdLE.Steps.Mailbox → metadata for mailbox steps
• IdLE.Steps.DirectorySync → metadata for directory sync steps

Architecture

IdLE.Core
  └── Foundational step infrastructure

IdLE.Steps.Common (requires IdLE.Core)
  └── Reusable step implementations

IdLE.Steps.* (requires IdLE.Core)
  └── Domain-specific step implementations

Third-party step packs can now depend solely on IdLE.Core without pulling in the common step library.

Breaking Changes (pre-1.0)

• Step packs must add IdLE.Core to RequiredModules

Testing

All 351 tests pass. Step discovery, metadata resolution, and provider method invocation verified.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Move generic step infrastructure into IdLE.Core and keep IdLE.Steps.Common as step implementations</issue_title>
<issue_description>## Problem Statement

IdLE.Steps.Common currently bundles two different concerns:

1. Generic step infrastructure (shared step types/contracts/registration/metadata & helpers that all step packs rely on)
2. Generic step implementations (actual “common steps”)

This makes the dependency graph less clear and makes it harder to reason about which parts are engine foundations vs. step library implementations.

We want a clearer layering where all step packs (including third-party) are expected to rely on IdLE.Core as the foundational layer, and IdLE.Steps.Common becomes a pure library of reusable step implementations.

Target date: 2026-01-31

Proposed Solution

Refactor the modules so that all generic step foundations live in IdLE.Core, while IdLE.Steps.Common contains only step implementations.

Goals

• IdLE.Core becomes the single foundational dependency for:
  • step definitions / base types / generic helpers required by steps at runtime
  • step registration/discovery (metadata catalog) if it is part of orchestration
  • any step execution contracts used by the engine
• IdLE.Steps.Common becomes pure step implementations (e.g., Ensure*, Disable*, etc.)
• First-party step packs (e.g., IdLE.Steps.Mailbox, IdLE.Steps.DirectorySync) depend on:
  • IdLE.Core (always)
  • IdLE.Steps.Common only when they reuse/extend common step implementations

Scope of changes (high level)

1. Identify all “generic step foundation” components currently in IdLE.Steps.Common:
   • contracts / types
   • metadata/registration mechanisms
   • shared runtime helpers used by step packs
2. Move these components into IdLE.Core:
   • preserve public surface area as much as possible
   • or provide compatibility shims if needed (pre-1.0: breaking changes are acceptable but must be explicit)
3. Adjust all first-party step packs to reference the new locations.
4. Ensure the engine/plan builder continues to discover and execute step types correctly.
5. Update documentation and examples to reflect the new layering.

Acceptance criteria

• IdLE.Steps.Common contains only step implementations (no foundational step contracts/registry).
• All first-party step packs run successfully with IdLE.Core providing the foundational step infrastructure.
• Tests pass (unit tests for step discovery/registration + any contract tests affected).
• Documentation clearly states:
  • “Step packs require IdLE.Core”
  • “IdLE.Steps.Common is optional and provides reusable step implementations”

Implementation checklist (agent-ready)

• Inventory: list each file/type/function moving from IdLE.Steps.Common to IdLE.Core and why
• Move/refactor code with a clear public/private structure
• Update module manifests (exports and RequiredModules as applicable)
• Update step discovery/registration paths
• Update examples and docs (single source of truth; other docs reference it)
• Add/adjust Pester tests covering:
  - step registration/discovery
  - execution of at least one step from IdLE.Steps.Common and one from another pack
• Add release notes entry describing the behavior change (breaking if applicable)

Alternatives Considered

• Split IdLE.Steps.Common into IdLE.Steps.Abstractions + IdLE.Steps.Common instead of moving abstractions into Core.
  • Rejected for now: we want the foundational dependency for all steps to be IdLE.Core and avoid introducing additional foundational modules unless necessary.
• Keep current structure.
  • Rejected: the mixed responsibilities make the layering unclear and complicate future scaling with many step packs.

Impact

• Potential breaking change (pre-1.0 acceptable):
  • Step packs may need updated imports/RequiredModules or updated type/function references after the move.
• Documentation and examples must be updated accordingly.
• May require updates to any third-party steps that depended on internals of IdLE.Steps.Common.

Additional Context

• Design decision: third-party steps are expected to rely on IdLE.Core (engine foundations).
• IdLE.Steps.Common should remain a reusable step implementation library, not a foundational layer.
  </issue_description>

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

• Fixes Move generic step infrastructure into IdLE.Core and keep IdLE.Steps.Common as step implementations #133

---

💡 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.

[Copilot]

Pull request overview

This PR clarifies module layering by making IdLE.Core the foundational dependency for step infrastructure, while keeping IdLE.Steps.Common focused on reusable step implementations. This enables first- and third-party step packs to depend on IdLE.Core without pulling in step implementation libraries.

Changes:

• Update first-party step pack manifests to require IdLE.Core.
• Make IdLE.Steps.Common explicitly require IdLE.Core.
• Export step infrastructure helpers (Invoke-IdleProviderMethod, Test-IdleProviderMethodParameter) from IdLE.Core and improve their comment-based help.

Reviewed changes

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

Show a summary per file

File	Description
src/IdLE.Steps.Mailbox/IdLE.Steps.Mailbox.psd1	Adds IdLE.Core as a required module for the mailbox step pack.
src/IdLE.Steps.DirectorySync/IdLE.Steps.DirectorySync.psd1	Adds IdLE.Core as a required module for the directory sync step pack.
src/IdLE.Steps.Common/Public/Get-IdleStepMetadataCatalog.ps1	Refines help text to reflect “common” step metadata and updates example output.
src/IdLE.Steps.Common/IdLE.Steps.Common.psd1	Makes IdLE.Steps.Common depend on IdLE.Core.
src/IdLE.Core/Public/Test-IdleProviderMethodParameter.ps1	Adds comment-based help for the provider parameter inspection helper.
src/IdLE.Core/Public/Invoke-IdleProviderMethod.ps1	Adds comment-based help for the provider invocation helper.
src/IdLE.Core/IdLE.Core.psm1	Exports the provider invocation/inspection helpers from IdLE.Core.
src/IdLE.Core/IdLE.Core.psd1	Updates FunctionsToExport to include the provider invocation/inspection helpers.

Comments suppressed due to low confidence (1)

src/IdLE.Core/Public/Invoke-IdleProviderMethod.ps1:18

• The help text says this helper “validates provider existence”, but the implementation does not check whether Context.Providers[$ProviderAlias] is present before dereferencing it. If the alias is missing, this will throw a null-reference error rather than a clear message. Either add an explicit provider existence/type check (and throw a descriptive error) or adjust the documentation to match the actual behavior.