Evaluate PowerShell Gallery packaging for hydration and VM reconnect

[kristopherjturner]

Summary

Evaluate whether azurelocal-hydration-vm-reconnect should evolve into one or more PowerShell Gallery deliverables, and define the right packaging, scope, and documentation strategy for hydration versus VM reconnect.

Problem

This repo currently combines two related but distinct areas:

• hydration
• VM reconnect

We need to determine whether this should remain a single solution or be broken into two separate deliverables.

A key requirement for any research, design, or AI-assisted implementation work on this repo is that it must understand the difference between hydration and VM reconnect. These are not interchangeable concepts and should not be treated as one feature unless the technical analysis proves that a single packaging model is justified.

Context

• There is no official Microsoft Docs coverage for this scenario today.
• There may be Microsoft technical blogs or community/blog content that discuss parts of the workflow, but there is not an official docs baseline to anchor to.
• I will provide preview release items and an external PowerShell blog from a trusted source that already does similar work in PowerShell.
• Some Azure Local / Az Stack HCI commands already exist in 2603 or related Azure Local builds and those should be inventoried and documented at least at the Azure resource / command surface level.

Goals

• decide whether this should become a PowerShell Gallery item
• decide whether it should become:
  • one module/package
  • two modules/packages
  • or a shared module with clearly separated hydration and VM reconnect entry points
• document existing built-in Azure Local / Az Stack HCI commands that overlap with or influence this repo
• avoid designing around assumptions that blur hydration and VM reconnect into the same thing without evidence

Scope

1. Research packaging direction

• assess whether this repo is a good candidate for PowerShell Gallery distribution
• identify the likely module boundaries, exported commands, versioning model, and dependency model
• compare a single-module approach versus split modules

2. Separate domain analysis

• define hydration clearly
• define VM reconnect clearly
• identify shared primitives versus domain-specific operations
• recommend whether the repo should stay unified or split into two tracks

3. Source review

• review the preview release items that will be provided
• review the external PowerShell blog/reference implementation that will be provided
• review any discoverable Microsoft technical blogs or product guidance that discuss the same space
• inventory any existing Azure Local / Az Stack HCI commands in 2603 or later builds that are already relevant

4. Documentation baseline

• create at least an internal documentation plan for:
  • command inventory
  • module boundaries
  • overlaps with built-in Azure resources/commands
  • gaps that still require custom tooling

Required Guidance For AI Or Contributors

Any AI agent or contributor working this issue must explicitly handle these rules:

• do not treat hydration and VM reconnect as the same feature by default
• do not assume there is official Microsoft Docs coverage when there is not
• use provided preview items and external references as inputs, but distinguish them from official product documentation
• identify where existing Azure Local / Az Stack HCI commands already solve part of the problem before proposing new commands
• call out clearly when a proposal is product-aligned versus custom community/tooling behavior

Key Questions

• Is this repo truly one product surface, or does it contain two separable tools?
• If split, should the split be by module, by command namespace, or by repo?
• What commands already exist in Azure Local / Az Stack HCI that reduce the need for custom implementation?
• Which capabilities are appropriate for PowerShell Gallery packaging versus repo-local scripts?
• What minimum documentation is required before any public packaging decision is made?

Acceptance Criteria

• A recommendation exists for PowerShell Gallery packaging strategy
• The recommendation explicitly addresses one module versus two modules
• Hydration and VM reconnect are documented as separate concepts with shared vs distinct responsibilities called out
• Existing Azure Local / Az Stack HCI commands relevant to this space are inventoried and documented
• Preview release items and the provided PowerShell blog/reference are reviewed as inputs
• The issue output includes a recommended next-step plan for implementation and documentation

Notes

This is primarily a research, architecture, and packaging-direction issue. The first outcome should be a decision-quality analysis, not immediate code churn.

[kristopherjturner]

Tracked in Azure DevOps: https://dev.azure.com/hybridcloudsolutions/Azure%20Local%20VM%20Hydration/_workitems/edit/168