Add Reset-PSResourceRepository cmdlet for repository store recovery

[Copilot]

Summary

This PR implements a new Reset-PSResourceRepository cmdlet that addresses the issue where users cannot recover from a corrupted PSResourceRepository.xml file. When the repository store becomes corrupted, users encounter parse errors and are left without a clear remediation path.

Fixes #[issue_number]

Problem

When the PSResourceRepository.xml file becomes corrupted, PSResourceGet throws parse errors that prevent any repository operations from working. Users are unable to fix the issue without manually locating and deleting the XML file, which is not intuitive or well-documented.

Example error:

Repository store may be corrupted, file reading failed with error: <error details>

Solution

This PR introduces the Reset-PSResourceRepository cmdlet that provides a safe, built-in way to recover from repository store corruption by:

1. Deleting the existing (potentially corrupted) PSResourceRepository.xml file
2. Creating a fresh repository store with the correct structure
3. Registering PSGallery with default settings (Priority: 50, Trusted: false)

Key Features

• Safe by default: Implements SupportsShouldProcess with ConfirmImpact.High, prompting users for confirmation before resetting
• Preview capability: Supports -WhatIf to preview what will be reset without making changes
• Flexible: Supports -Confirm:$false for automation scenarios
• Observable: Supports -PassThru to return the PSGallery repository information after reset
• Discoverable: Error messages in CheckRepositoryStore() now suggest using this cmdlet when corruption is detected

Usage Examples

# Reset with confirmation prompt (default behavior)
Reset-PSResourceRepository

# Reset without confirmation for automation
Reset-PSResourceRepository -Confirm:$false

# Preview what would happen without making changes
Reset-PSResourceRepository -WhatIf

# Reset and return PSGallery repository info
$psGallery = Reset-PSResourceRepository -Confirm:$false -PassThru

Implementation Details

New Files

• src/code/ResetPSResourceRepository.cs: New cmdlet implementation
• test/ResourceRepositoryTests/ResetPSResourceRepository.Tests.ps1: Comprehensive test suite

Modified Files

• src/code/RepositorySettings.cs: Added ResetRepositoryStore() public method and improved error messaging
• src/Microsoft.PowerShell.PSResourceGet.psd1: Added cmdlet to exports
• CHANGELOG/preview.md: Documented new feature

Testing

Comprehensive test coverage includes:

• Resetting repository store with multiple repositories registered
• Resetting when only PSGallery exists
• -PassThru parameter functionality
• -WhatIf parameter (verifies no changes are made)
• Resetting when PSGallery was previously unregistered
• Resetting custom PSGallery settings back to defaults

All tests follow existing patterns in the repository test suite.

Design Decisions

1. Separate cmdlet rather than a parameter: Implemented as a standalone cmdlet (not Register-PSResourceRepository -Reset) for better discoverability and clearer intent
2. High confirm impact: Prevents accidental data loss of registered repositories
3. Code reuse: Leverages existing Add() method for consistency and reduced duplication
4. User guidance: Updated error messages to guide users to this solution when they encounter corruption

Related Comments

Addresses feedback from @StevenBucher98 regarding ShouldProcess logic to ensure users understand what is happening and where the file being reset is located.

Addresses feedback from @alerickson regarding documentation on handling reset scenarios.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• 1k9vsblobprodcus379.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• 37cvsblobprodcus359.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• 4myvsblobprodcus32.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• 51yvsblobprodcus36.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• 5dkvsblobprodcus355.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• 7devsblobprodcus323.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• 7k6vsblobprodcus337.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• 7tjvsblobprodcus341.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• bcnvsblobprodcus378.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• c50vsblobprodcus330.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• c78vsblobprodcus322.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• dlbvsblobprodcus316.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• fdpvsblobprodcus345.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• gbsvsblobprodcus365.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• kh4vsblobprodcus325.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• kmuvsblobprodcus389.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• l49vsblobprodcus358.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• m6xvsblobprodcus342.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• pkvvsblobprodcus321.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• s4uvsblobprodcus326.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• tphvsblobprodcus375.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• uy6vsblobprodcus34.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)
• yttvsblobprodcus357.vsblob.vsassets.io
  • Triggering command: /usr/bin/dotnet publish --configuration Debug --framework net472 --output bin/Debug/net472/publish (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Repository store (PSRepositories.xml) should have 'reset' functionality</issue_title>
<issue_description>### Prerequisites

• Write a descriptive title.
• Make sure you are able to repro it on the latest released version
• Search the existing issues.

Steps to reproduce

If the repository store gets corrupted, PSGet throws an error from attempting to parse the file. At the very least, error messaging should provide user with steps to remedy the situation. We should, however, also add either a new parameter or a new cmdlet that allows users to delete the old PSRepositories.xml file and create a new default file.

I'm proposing:
Register-PSResourceRepository -Reset
which, again, would delete the current PSRepositories.xml file, create a new one, and then register only the PowerShellGallery.

Expected behavior

If the xml file is unable to be parsed, an error throws telling the user that there was a parse error and suggesting to either try rerunning the command or running Register-PSResourceRepository -Reset to reset the repository store.

Actual behavior

Throws parse error and fails.

Error details

No response

Environment data

All versions and OS.

Visuals

No response</issue_description>

<agent_instructions>Create a new cmdlet called 'Reset-PSResourceRepository' that creates a fresh, brand new instance of the PSResourceRepository.xml file and add handling for 'whatif' condition</agent_instructions>

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

@StevenBucher98 Adding some ShouldProcess logic in order to make sure the user understands what is happening and where the file is that they are going to reset @alerickson @mgreenegit consider documentation on how to handle a 'reset' scenario

Fixes #611

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.