Refactor: Standardize Identity capability names to IdLE.Identity.*

[Copilot]

Summary

Standardizes all Identity capability names to use the canonical IdLE.Identity.* namespace, aligning with the existing IdLE.Entitlement.* pattern. No legacy support - only canonical names are accepted.

Motivation

The repository mixed Identity.* and IdLE.Entitlement.* naming, causing:

• Inconsistent capability validation across providers, workflows, and tests
• Cognitive overhead for contributors and provider authors
• Capability naming drift between docs and implementation

Type of Change

• Refactoring / internal improvement

Changes

Core updates:

• Updated Get-IdleProviderCapabilities.ps1 inference logic to emit canonical names
• Updated New-IdlePlanObject.ps1 capability validation to use canonical names directly
• Updated New-IdleMockIdentityProvider.ps1 to advertise canonical capabilities
• Updated workflow examples and documentation to use canonical names only

Capability names:

# Before (legacy - now invalid)
'Identity.Read'              
'Identity.Disable'           
'Identity.Attribute.Ensure'  

# After (canonical - required)
'IdLE.Identity.Read'
'IdLE.Identity.Disable'
'IdLE.Identity.Attribute.Ensure'

No backward compatibility:

• Legacy Identity.* names will fail validation
• No normalization or auto-conversion
• Cleaner, simpler implementation (220 lines removed)

Tests & docs:

• Updated all test assertions to expect canonical names
• Removed legacy acceptance tests (not needed)
• All examples and documentation use canonical names only

Testing

• Unit tests
• Manual testing

Test results:

• All 125 tests pass
• PSScriptAnalyzer: clean
• Only canonical names accepted

How to test & review

1. Verify all capability strings in code use IdLE.Identity.* format
2. Check that tests expect canonical names only
3. Verify no legacy Identity.* references remain in examples/docs
4. Confirm legacy names are rejected (not normalized)

Checklist

• Code follows STYLEGUIDE.md
• Tests added or updated
• Documentation updated
• No UI/auth logic added to IdLE.Core
• No breaking changes without discussion

Related Issues

Addresses standardization needed for #46 (AD Provider assumes canonical names).

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Refactor: Standardize Identity capability names to IdLE.Identity.*</issue_title>
<issue_description>## Goal

Standardize all Identity capability names across the repository to use the canonical namespace:

• Canonical: IdLE.Identity.*
• Legacy (deprecated): Identity.*

The repository currently uses a mix of Identity.* and IdLE.Entitlement.*. This issue makes Identity consistent with the existing IdLE.* namespacing approach.

Motivation

• Avoid capability naming drift between docs, examples, tests, and providers.
• Ensure plan-time validation behaves consistently (same names everywhere).
• Reduce cognitive load for contributors and for provider authors.

Scope

In scope

• Update all occurrences of Identity.* capabilities in:
  • Core capability validation / inference helpers (if present)
  • Built-in step metadata (RequiresCapabilities)
  • Mock provider capability advertisement
  • Provider contract tests and other unit tests
  • Example workflow configurations (demo runner workflows)
  • Documentation that references capability names

Out of scope

• Implementing new providers or new steps beyond capability renames.
• Changing the semantics of capabilities (this is a rename/standardization only).

Decisions

1) Canonical naming rule

All Identity capabilities MUST be named under the IdLE. namespace.

• ✅ Canonical: IdLE.Identity.Read
• ❌ Not allowed for new work: Identity.Read

2) Compatibility policy

Until v1.0.0, legacy Identity.* capability names are treated as deprecated aliases for IdLE.Identity.*.

• Engine/plan validation SHOULD accept legacy names when encountered.
• A warning event MUST be emitted when a legacy name is used (so users see it and can migrate).
• Documentation and examples MUST use canonical names only.

Rationale: This avoids breaking existing workflow configs immediately while enabling #46 and future work to rely on canonical names.

Canonical capability map (old → new)

Update capability strings as follows (exact matches):

Legacy name	Canonical name
Identity.Read	IdLE.Identity.Read
Identity.Disable	IdLE.Identity.Disable
Identity.Enable	IdLE.Identity.Enable
Identity.Create	IdLE.Identity.Create
Identity.Delete	IdLE.Identity.Delete
Identity.Move	IdLE.Identity.Move
Identity.List	IdLE.Identity.List
Identity.Attribute.Ensure	IdLE.Identity.Attribute.Ensure

Note: If the repository currently uses an alternative attribute capability name (e.g., Identity.EnsureAttribute), it MUST be normalized to the canonical form above as part of this issue.

Implementation notes

Where to implement alias support (if needed)

If a central normalization point exists (recommended), add a helper that:

• Receives a list of capability strings
• Normalizes them to canonical form
• Returns the canonical list
• Emits a warning event when legacy names are seen

Suggested behavior:

• Normalization is applied both to:
  • Provider-advertised capabilities
  • Step RequiresCapabilities

This ensures plan-time checks do not fail due to legacy naming.

Do not change semantics

This issue is renaming/standardization only:

• Do not change what the capability means
• Do not introduce new side effects

Tasks

Code

• Replace all Identity.* occurrences in core/steps/providers/tests/examples with IdLE.Identity.*.
• Ensure built-in steps declare canonical RequiresCapabilities.
• Update the mock provider to advertise canonical Identity capabilities.
• Add/adjust normalization/alias logic (until v1.0.0) and emit a warning event for legacy names.

Tests

• Update tests that assert capability names.
• Add tests for alias behavior (legacy name accepted, warning emitted, canonical name used internally).

Docs / Examples

• Update documentation to use canonical names.
• Update demo runner example workflows to use canonical names.

Acceptance criteria

• All repository code and examples use canonical IdLE.Identity.* capability names.
• All tests are green.
• PSScriptAnalyzer (or repo linting) remains green.
• Legacy Identity.* names are accepted until v1.0.0 AND produce a warning event.
• No documentation/examples reference Identity.* after this change.

Related issues

• IdLE.Provider.AD (On-Prem AD) MVP (Windows-only) #46 (AD Provider + steps) assumes canonical IdLE.Identity.* capability names.

Notes for reviewers

• This issue is intentionally cross-cutting; keep PRs small by grouping changes by area (e.g., core + tests, then docs + examples) or by doing one cohesive PR if CI time is acceptable.
• Ensure no capability strings remain in the legacy namespace.
  </issue_description>

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

...

• Fixes Refactor: Standardize Identity capability names to IdLE.Identity.* #85

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[blindzero]

@copilot Explain why it needs src/IdLE.Core/Private/ConvertTo-IdleCanonicalCapability.ps1 as a new function?

[Copilot]

@copilot Explain why it needs src/IdLE.Core/Private/ConvertTo-IdleCanonicalCapability.ps1 as a new function?

The ConvertTo-IdleCanonicalCapability.ps1 function centralizes the legacy-to-canonical capability name mapping in one place, following the DRY principle and the issue's recommendation for "a central normalization point."

Why it's needed:

1. Multiple normalization points: Capability names appear in three places that need normalization:

   • Provider-advertised capabilities (in Get-IdleProviderCapabilities.ps1)
   • Step requirements (in New-IdlePlanObject.ps1 - two locations: local function + nested function)

2. Maintainability: Without this function, the mapping table (Identity.Read → IdLE.Identity.Read) would be duplicated across 3+ locations, creating maintenance issues when adding new capabilities.

3. Future extensibility: The function is designed to support warning events (per the issue requirement: "A warning event MUST be emitted when a legacy name is used"). While not yet implemented at plan-time, the infrastructure is ready for when an EventSink becomes available.

Alternative considered: Inline the mapping in each location, but that violates DRY and makes updates error-prone (miss one location = inconsistent behavior).

The function is 80 lines but most of that is documentation and the capability mapping table—the actual logic is ~15 lines. This is a standard pattern for centralized normalization/translation functions.

[blindzero]

@copilot About 1. I dont need or want any legacy support. We just and only support the new way and need to make sure that this is everywhere included.

Does 2 and 3 then still applies? Why is the mapping describd in 2 needed anyways / at all?

[Copilot]

@copilot About 1. I dont need or want any legacy support. We just and only support the new way and need to make sure that this is everywhere included.

Does 2 and 3 then still applies? Why is the mapp...

You're right - I misunderstood the requirement. The issue description mentioned "legacy support" but you want a clean cut to canonical names only, with no backward compatibility layer.

What this means:

The ConvertTo-IdleCanonicalCapability.ps1 function and all normalization logic should be removed. Instead:

1. Simply update all capability strings directly to canonical form (already done in most places)
2. No mapping/normalization needed - if someone uses Identity.Read it should fail validation, not be auto-converted
3. Tests should verify that only canonical names work, not test legacy acceptance

I'll remove the normalization function and clean up the code to use direct canonical names everywhere. The change will be simpler and clearer.

@copilot About 1. I dont need or want any legacy support. We just and only support the new way and need to make sure that this is everywhere included.

Does 2 and 3 then still applies? Why is the mapp...

Fixed in commit 6765325.

Changes made:

1. Removed ConvertTo-IdleCanonicalCapability.ps1 entirely
2. Removed all normalization logic from capability discovery and validation
3. Removed 4 tests that tested legacy name acceptance

Result:

• Only canonical IdLE.Identity.* names are accepted
• Using legacy names (e.g., Identity.Read) will fail validation - no auto-conversion
• Simpler, cleaner code: 220 lines removed
• All 125 tests passing

The codebase now enforces canonical names only, with no backward compatibility layer.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6765325b48

ℹ️ 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 standardizes all Identity capability names to use the canonical IdLE.Identity.* namespace, aligning with the existing IdLE.Entitlement.* pattern. The refactoring removes the mixed usage of Identity.* and properly namespaced capabilities throughout the codebase.

Changes:

• Updated all capability strings from Identity.* to IdLE.Identity.* across core functions, providers, tests, and examples
• Removed backward compatibility logic (no aliases or normalization)
• Updated all documentation and examples to use canonical naming only

Reviewed changes

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

Show a summary per file

File	Description
tests/New-IdlePlan.Capabilities.Tests.ps1	Updated test assertions to expect canonical IdLE.Identity.* capability names in validation error messages and plan objects
tests/Get-IdleProviderCapabilities.Tests.ps1	Updated mock provider capability advertisement and test assertions to use canonical names
src/IdLE.Provider.Mock/Public/New-IdleMockIdentityProvider.ps1	Updated GetCapabilities() method to return canonical IdLE.Identity.* capability names
src/IdLE.Core/Public/New-IdlePlanObject.ps1	Updated error message example from Identity.Read to IdLE.Identity.Read
src/IdLE.Core/Private/Get-IdleProviderCapabilities.ps1	Updated capability inference logic to emit canonical names and updated error messages with canonical examples
examples/workflows/joiner-with-onfailure.psd1	Updated RequiresCapabilities from Identity.Attribute.Ensure to IdLE.Identity.Attribute.Ensure
examples/workflows/joiner-ensureentitlement.psd1	Updated RequiresCapabilities from Identity.Attribute.Ensure to IdLE.Identity.Attribute.Ensure
docs/usage/steps.md	Updated capability reference from Identity.Attribute.Ensure to IdLE.Identity.Attribute.Ensure
docs/advanced/provider-capabilities.md	Updated all capability examples and documentation to use canonical IdLE.Identity.* format

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[blindzero]

@copilot I was referring to this finding:

src/IdLE.Core/Public/New-IdlePlanObject.ps1
Comment on lines 165 to +167

Normalize legacy Identity. capability aliases*

This normalization step only trims/validates and then compares raw strings, so legacy capability names remain un-mapped. With this commit updating workflows/docs/tests to IdLE.Identity., any existing provider that still advertises Identity. (or vice‑versa) will now fail plan validation with MissingCapabilities even though it can satisfy the step. The repo’s AGENTS.md explicitly states that legacy capability names should be treated as deprecated aliases during migration, so the lack of alias normalization/warning here is a breaking regression for existing providers and workflows.