Enhance Chocolatey Module with license management

.github/copilot-instructions.md

@@ -14,6 +14,8 @@
 - This module is Windows-only.
 - This module must support Windows PowerShell 5.1 and PowerShell 7.
 - The built module is imported as `Chocolatey`.
+- Custom GitHub wiki content lives under `source/WikiSource` and is published through the Sampler/DscResource.DocGenerator wiki tasks.
+- New or updated functions must keep comment-based help complete, including at least one `.EXAMPLE`, because `tests/QA/module.tests.ps1` enforces help examples for both public and private functions.
 - Add an `Unreleased` changelog entry in `CHANGELOG.md` for behavior or workflow changes.
 
 ## Instruction files

.github/instructions/private-functions.instructions.md

@@ -7,7 +7,7 @@ applyTo: 'source/private/**/*.ps1'
 
 ## Baseline structure
 
-- Follow the same comment-based help baseline as public functions.
+- Follow the same comment-based help baseline as public functions, including at least one `.EXAMPLE`.
 - Use `[CmdletBinding()]`.
 - Include `[OutputType(...)]` when output shape is stable and meaningful to document.
 - Use explicit parameter types where the helper contract is stable.
@@ -23,6 +23,7 @@ applyTo: 'source/private/**/*.ps1'
 
 - Add or update matching tests under `tests/Unit/Private/<FunctionName>.tests.ps1`.
 - Cover happy path and validation or failure behavior.
+- Keep help examples current when adding or changing private helpers; repository QA checks fail when a function has no `.EXAMPLE`.
 - Prefer focused validation first:
 
 ```powershell

.github/instructions/public-functions.instructions.md

@@ -29,6 +29,8 @@ applyTo: 'source/public/**/*.ps1'
 
 - Add or update matching tests under `tests/Unit/Public/<FunctionName>.tests.ps1`.
 - Cover happy path and validation or failure behavior.
+- If the command uses the hidden `RunNonElevated` guard pattern (`$RunNonElevated = $(Assert-ChocolateyIsElevated)`), update tests to either pass `-RunNonElevated` or explicitly mock the elevation check so unit tests exercise the intended behavior instead of failing at parameter binding time.
+- When command resolution behavior is under test, mock `Get-ChocolateyCommand` rather than older `Get-Command -Name 'choco.exe'` call paths unless the implementation still uses `Get-Command` directly.
 - Prefer focused validation first:
 
 ```powershell

.github/instructions/test-writing.instructions.md

@@ -46,6 +46,8 @@ BeforeAll {
 - When validating class or type-accelerator behavior, import the module before invoking code paths that reference exported accelerators.
 - Use PowerShell-version or platform guards only when the behavior truly differs between Windows PowerShell 5.1 and PowerShell 7.
 - This repository is Windows-only, but tests must still work on both supported PowerShell versions.
+- For commands that mutate system state and use the hidden `RunNonElevated` parameter defaulted from `Assert-ChocolateyIsElevated`, unit tests should normally pass `-RunNonElevated` unless the elevation check itself is the subject of the test.
+- Mock the command-discovery helper that the implementation actually uses. In this repository that is usually `Get-ChocolateyCommand`, not `Get-Command`.
 
 ## Validation commands
 

.github/instructions/wiki-publishing.instructions.md

@@ -0,0 +1,30 @@
+---
+description: 'GitHub wiki content and publishing instructions'
+applyTo: 'source/WikiSource/**/*.md,build.yaml,.pipelines/*.yml,.pipelines/*.yaml'
+---
+
+# GitHub Wiki Publishing Guidelines
+
+## Source of truth
+
+- Keep hand-authored GitHub wiki pages under `source/WikiSource`.
+- Treat `source/WikiSource` as the canonical source for custom wiki pages; do not edit generated files under `output/WikiContent`.
+- Prefer stable page names in `WikiSource` so published wiki links do not churn.
+
+## Build wiring
+
+- Keep wiki generation and publishing wired through `build.yaml`.
+- Ensure docs/build workflows that prepare wiki content include `Copy_Source_Wiki_Folder` so `source/WikiSource` is copied into `output/WikiContent`.
+- Keep `Publish_GitHub_Wiki_Content` in the `publish` workflow so the generated wiki content is pushed to the repository wiki.
+- Keep `Generate_Wiki_Sidebar` after copying `WikiSource` content so custom pages can participate in sidebar generation.
+
+## Authoring notes
+
+- Put landing-page content in `source/WikiSource/Home.md` when a custom wiki home page is needed.
+- If `Home.md` contains module version placeholders, rely on the Sampler/DscResource.DocGenerator task to update them during the build; do not hardcode release-specific versions into committed wiki pages.
+- Keep custom wiki content in Markdown that is compatible with GitHub wiki rendering.
+
+## Validation
+
+- After changing wiki workflow wiring or `source/WikiSource` structure, validate with `./build.ps1 -Tasks build`.
+- When changing publish behavior, also validate the docs/publish path used by the pipeline rather than editing `output/WikiContent` manually.

.gitignore

@@ -22,3 +22,5 @@ modules/*
 .kitchen/*
 .kitchen.local.yml
 **/bin
+
+chocolatey.license.*

CHANGELOG.md

@@ -23,6 +23,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated the Copilot setup workflow to resolve the built module artifact
   dynamically and run on Windows so the built module can be imported during
   environment validation.
+- Hardened Chocolatey delimited output parsing so licensed-extension
+  compatibility output is surfaced as warnings or errors and is no longer
+  treated as installed package data.
+- Added regression coverage for the `ChocolateyPackage` DSC/class `Get()`
+  path so licensed-extension compatibility warnings still resolve to an
+  absent package state instead of breaking package discovery.
+- Added `Install-ChocolateyLicense` to install or overwrite a Chocolatey
+  license file from a source path or XML content.
+- Added `Remove-ChocolateyLicense` to remove the Chocolatey license file and
+  revert to unlicensed Chocolatey behavior.
+- Aligned wiki generation with the explicit Sampler docs workflow so content
+  from `source\WikiSource` is prepared and published to the GitHub wiki.
+- Added a `Home.md` wiki landing page under `source\WikiSource`.
+- Added a `LicensedChocolatey.md` wiki page covering license install, removal,
+  and the licensed-extension compatibility warning.
 
 ### Fixed
 

build.yaml

@@ -41,12 +41,24 @@ BuildWorkflow:
     - Build_Module_ModuleBuilder
     - Build_NestedModules_ModuleBuilder
     - Create_changelog_release_output
+    - Create_Wiki_Output_Folder
     - Generate_Conceptual_Help
-    - Generate_Wiki_Content
+    - Generate_Markdown_For_Public_Commands
+    - Generate_External_Help_File_For_Public_Commands
+    - Clean_Markdown_Of_Public_Commands
+    - Generate_Markdown_For_DSC_Resources
+    - Copy_Source_Wiki_Folder
+    - Generate_Wiki_Sidebar
+    - Clean_Markdown_Metadata
 
   docs:
+    - Create_Wiki_Output_Folder
     - Generate_Conceptual_Help
-    - Generate_Wiki_Content
+    - Generate_Markdown_For_Public_Commands
+    - Generate_External_Help_File_For_Public_Commands
+    - Clean_Markdown_Of_Public_Commands
+    - Generate_Markdown_For_DSC_Resources
+    - Copy_Source_Wiki_Folder
     - Generate_Wiki_Sidebar
     - Clean_Markdown_Metadata
     - Package_Wiki_Content

source/Classes/002.ChocolateyPackage.ps1

@@ -391,7 +391,7 @@ class ChocolateyPackage : ChocolateyBase
                 Write-Error -Message ('Unsupported error occurred while processing {0}.' -f $DesiredState.Name)
             }
 
-            Default
+            default
             {
                 # Unsupported Code Path
                 Write-Error -Message ('Unsupported code path encountered while processing {0}.' -f $DesiredState.Name)

source/WikiSource/Home.md

@@ -0,0 +1,47 @@
+# Chocolatey Module Wiki
+
+The **Chocolatey Module** provides PowerShell commands and DSC resources for installing Chocolatey, managing packages, sources, features, settings, and related automation tasks.
+
+## Start here
+
+- Install Chocolatey CLI with the `ChocolateySoftware` DSC resource.
+- Manage packages with the `ChocolateyPackage` DSC resource.
+- Manage package sources with the `ChocolateySource` DSC resource.
+- Manage Chocolatey settings with the `ChocolateySetting` DSC resource.
+- Manage Chocolatey features with the `ChocolateyFeature` DSC resource.
+- Install a Chocolatey license with the `Install-ChocolateyLicense` command.
+- [Licensed Chocolatey guidance](LicensedChocolatey.md)
+
+## Migration
+
+- [cChoco migration guide](cChocoMigrationWiki.md)
+
+## Command reference
+
+Generated command pages in the published wiki include:
+
+- `Install-ChocolateySoftware`
+- `Install-ChocolateyLicense`
+- `Remove-ChocolateyLicense`
+- `Install-ChocolateyPackage`
+- `Update-ChocolateyPackage`
+- `Uninstall-ChocolateyPackage`
+- `Register-ChocolateySource`
+- `Set-ChocolateySetting`
+- `Enable-ChocolateyFeature`
+
+## DSC resources
+
+Generated DSC resource pages in the published wiki include:
+
+- `ChocolateySoftware`
+- `ChocolateyPackage`
+- `ChocolateySource`
+- `ChocolateySetting`
+- `ChocolateyFeature`
+
+## Notes
+
+- The repository is Windows-only.
+- The module supports Windows PowerShell 5.1 and PowerShell 7.
+- Generated command pages and `_Sidebar.md` are rebuilt from `build.yaml`; keep custom wiki pages in `source\WikiSource`.

source/WikiSource/LicensedChocolatey.md

@@ -0,0 +1,68 @@
+# Licensed Chocolatey
+
+This module now includes public commands to install and remove a Chocolatey license file:
+
+- `Install-ChocolateyLicense`
+- `Remove-ChocolateyLicense`
+
+## Installing a license
+
+You can install a license either from a file path or from raw XML content.
+
+### From a file
+
+```powershell
+Install-ChocolateyLicense -Path 'C:\secure\chocolatey.license.xml'
+```
+
+### From XML content
+
+```powershell
+$licenseXml = Get-Content -Path 'C:\secure\chocolatey.license.xml' -Raw
+Install-ChocolateyLicense -Content $licenseXml
+```
+
+The command writes the license to Chocolatey's standard machine-wide location:
+
+```text
+<ChocolateyInstall>\license\chocolatey.license.xml
+```
+
+If a license file already exists, `Install-ChocolateyLicense` overwrites it.
+
+## Removing a license
+
+To revert a machine back to unlicensed Chocolatey behavior:
+
+```powershell
+Remove-ChocolateyLicense
+```
+
+This removes:
+
+```text
+<ChocolateyInstall>\license\chocolatey.license.xml
+```
+
+## Licensed extension compatibility warning
+
+If the license file exists but `chocolatey.extension` is not installed yet, Chocolatey can emit a compatibility warning similar to:
+
+```text
+A valid Chocolatey license was found, but the chocolatey.licensed.dll assembly could not be loaded:
+```
+
+The module now surfaces that message on the **warning stream** and ignores it when parsing package list output, so it is no longer misinterpreted as installed package data.
+
+You should still install the licensed extension promptly after installing the license:
+
+```powershell
+Install-ChocolateyPackage -Name 'chocolatey.extension'
+```
+
+## Recommended sequence
+
+1. Install Chocolatey CLI.
+2. Install the Chocolatey license.
+3. Install `chocolatey.extension`.
+4. Continue with the rest of your licensed configuration.